API Reference

Workestra exposes two authenticated developer surfaces:

REST API under /api/v1 for resource-oriented integrations.
Hosted MCP tool API under /api/mcp for AI clients using the workestra-mcp STDIO adapter.

The supported REST contract contains 7 paths and 17 HTTP operations. The Public API Status page is the authoritative support boundary.

Giving this page to an AI assistant? Ask it to read the AI Agent Integration Guide first. For broad AI automation, prefer MCP: it exposes live, permission-aware tool schemas. Do not probe unlisted REST routes or guess request fields.

Canonical origin

https://platform.workestra.app

Use the platform origin directly. The apex and www origins are marketing surfaces, and API clients can discard an Authorization header when following a cross-host redirect.

REST base URL:

https://platform.workestra.app/api/v1

Hosted MCP endpoints:

GET      /api/mcp/session
GET|POST /api/mcp/tools/list
POST     /api/mcp/tools/call

Start here

Goal	Documentation
Hand this integration to an AI agent	AI Agent Integration Guide
Choose MCP versus REST	AI Agent Integration Guide
Run REST smoke tests	Testing guide
Follow an end-to-end workflow	Integration recipes
Diagnose an error or missing tool	Troubleshooting
See every supported REST path and method	Public API Status
Create and scope an API key	Authentication
Test MCP tools and retrieve their schemas	MCP tool discovery
Configure Codex, Claude, Cursor, or VS Code	MCP Server
Verify outbound webhook signatures	Webhooks
Check OpenAPI publication status	OpenAPI

Authentication

Use a Workestra API key in the bearer header:

Authorization: Bearer wks_your_api_key

API keys are workspace-scoped, revocable, may expire, and are shown only once. The /api/v1 implementation also accepts an authenticated Workestra session JWT for first-party clients. Third-party integrations should use API keys.

Response conventions

Most v1 success responses use:

{
  "data": {},
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 1,
    "hasMore": false
  }
}

pagination is present only on paginated list responses. A small number of older handlers return their created object directly; check the endpoint guide or actual response before generating a strict client.

Most v1 errors use:

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Valid authentication required"
  }
}

Quota and MCP errors have older flat envelopes. Test clients should primarily branch on HTTP status and then read either error.message or a string error.

Supported REST resources

The public contract covers contacts, deals, projects, and issues/tasks. See the endpoint guides for fields, examples, and edge cases. For other Workestra areas, use the live MCP tool catalog rather than probing application routes.

The legacy Supabase Edge Function families /api-contacts, /api-deals, /api-issues, /api-projects, and /api-ingest are not the current REST contract. Do not use them for new integrations.

Contract maturity

OpenAPI publication is temporarily paused while the sanitized application artifact is released. Use the dedicated guides and runtime validation during today's tests. See OpenAPI status.

Contract levels

Level	Meaning	Agent behavior
Guide	Fields and important behavior are documented	Safe to implement after reading the guide
Live MCP schema	Deployed tool schema and permission result	Safe to call after retrieving the schema
Deprecated	Compatibility route	Do not use for new work
Internal	Not a public integration contract	Do not call

Agent handoff prompt

A nontechnical user can give an assistant this URL and instruction:

Read https://docs.workestra.app/docs/api and its AI Agent Integration Guide.
Prefer MCP for broad automation. Never ask me to paste an API key into chat.
Retrieve live tool schemas before calls, explain writes before executing them,
use disposable data for tests, and stop rather than guessing an unlisted REST
contract. For unresolved integration errors, prepare a sanitized report for
support@workestra.app.

Integration support

Email support@workestra.app. Include the workspace ID, UTC timestamp, method/path or MCP tool, status, request/delivery ID, client version, sanitized request/response, and reproduction steps. Never include API keys, tokens, private attachment URLs, or unnecessary personal data.

API Reference

On this page