Production REST and GraphQL reference

API Reference

Complete reference for the ServoAgent REST and GraphQL APIs, backed by the same published OpenAPI spec served from the platform.

Base URL

https://api.servoagent.com/v1

Use JSON request and response bodies, send a Bearer API key on every authenticated request, and include `X-Request-Id` when you need client-side traceability.

OpenAPI JSON OpenAPI YAML API Explorer

Authentication

Bearer API keys

Workspace-scoped keys with granular scopes and rotation support.

Spec format

OpenAPI 3.1

JSON and YAML specs are published from the same service used by the platform.

Live tooling

REST + GraphQL

Use the Explorer for live requests and generated snippets across supported SDKs.

Core resources

Every resource page includes scopes, request examples, and endpoint-level summaries.

Agents

Create, version, and execute agents. Agents are the core runtime unit for automation workflows.

View docs

GET/agents

List all agents in the workspace.

POST/agents

Create a new agent draft.

GET/agents/{agentId}

Fetch a single agent by ID.

PATCH/agents/{agentId}

Update agent metadata and config.

DELETE/agents/{agentId}

Delete an existing agent.

POST/agents/{agentId}/execute

Execute the agent and create a run record.

Runs

Inspect runtime status, outputs, and step traces for every agent execution.

View docs

GET/runs

List runs with status filtering.

GET/runs/{runId}

Get a run with output payload.

GET/runs/{runId}/steps

Retrieve ordered execution steps for observability.

Contacts

Store and update contact records for CRM integrations and audience segmentation.

View docs

GET/contacts

List contacts with paging and search.

POST/contacts

Create a new contact.

GET/contacts/{contactId}

Fetch one contact record.

PATCH/contacts/{contactId}

Update profile fields.

DELETE/contacts/{contactId}

Delete a contact.

Webhooks

Subscribe to events, test deliveries, and rotate webhook secrets securely.

View docs

GET/webhooks

List webhook endpoints.

POST/webhooks

Create a webhook endpoint.

POST/webhooks/{webhookId}/test

Trigger a test event delivery.

GET/webhooks/{webhookId}/deliveries

Review delivery attempts and status.

POST/webhooks/{webhookId}/rotate-secret

Rotate endpoint signing secret.

DELETE/webhooks/{webhookId}

Delete a webhook endpoint.

API Keys

Create, rotate, and revoke keys used by production integrations and background jobs.

View docs

GET/keys

List workspace API keys.

POST/keys

Create a new scoped API key.

DELETE/keys/{keyId}

Revoke an active API key.

POST/keys/{keyId}/roll

Rotate a key without changing client workflows.

GraphQL

Use the explorer and GraphQL endpoint for flexible read-heavy integrations and internal tooling.

View docs

POST/graphql

Execute GraphQL queries and mutations.

Request headers

Header	Required	Description
`Authorization`	Yes	Bearer token using a workspace API key.
`Content-Type`	POST/PATCH	Use application/json for request bodies.
`X-Request-Id`	Optional	Client-provided trace identifier for support and observability.

Pagination shape

{
  "data": [...],
  "pagination": {
    "total": 100,
    "limit": 20,
    "offset": 40,
    "hasMore": true
  }
}

Error envelope

{
  "error": {
    "code": "invalid_request",
    "message": "agentId is required",
    "requestId": "req_01HXYZ..."
  }
}