Eos Developers
Design target — not live yet. This documentation defines the contract Eos will implement. Existing internal application APIs are not part of this contract.

Building Eos integrations with LLMs

Eos publishes the same API contract in three machine-friendly forms so coding agents can work without an MCP server:

  • OpenAPI 3.1 JSON is the canonical machine-readable contract.
  • Markdown documentation provides behavior, security boundaries, examples, and business meaning that schemas alone cannot express.
  • llms.txt gives an LLM a small discovery index with stable URLs.

The OpenAPI document contains stable operationId values, OAuth client-credentials security, problem schemas, idempotency and concurrency headers, and x-eos-* authorization metadata. Give both the OpenAPI URL and the relevant Markdown page to an LLM. The OpenAPI file tells it what to call; the Markdown explains how the operation should behave.

Recommended prompt packet

Provide the coding agent with:

  1. https://eoshq.com/developers/api/v1/openapi.json
  2. The relevant pages under https://eoshq.com/developers/api/v1/markdown/
  3. The integration's desired workflow and test organization
  4. An API Client ID and secret through a secret manager or local environment variables—not in the prompt, source code, logs, or chat transcript

Ask the agent to obtain a short-lived token from POST /oauth/token, use only operations in the OpenAPI file, preserve Idempotency-Key values across retries, honor ETag/If-Match, and treat member IDs as normalized email addresses.

API Playground

The API Playground can obtain a token and execute calls from the browser. Credentials remain in the page's memory and are cleared on refresh. Use a narrowly fenced test API Client; never paste a production secret into a shared screen, recording, or third-party browser extension.

Generated clients and tool calling

OpenAPI generators can create typed clients. LLM tool-calling frameworks can also convert selected OpenAPI operations into tools. Do not expose all operations automatically: select the smallest operation set required for the workflow, even though Eos independently enforces the API Client's license and Roles.

An LLM must not infer that a member subject is the actor. In Agents and Conversations, the API Client remains the actor and the optional subject contributes no Eos Roles, record access, personal provider connection, or identity.

Contract updates

Pin generated integrations to API v1 and preserve unknown response fields. Eos will make additive changes inside v1, while incompatible behavior requires a new API version. Re-fetch the OpenAPI document during planned upgrades rather than silently regenerating production code.

Next: Organization API.