# 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](/developers/api/v1/openapi.json) is the canonical machine-readable contract.
- [Markdown documentation](/developers/api/v1/markdown/index.md) provides behavior, security boundaries, examples, and business meaning that schemas alone cannot express.
- [`llms.txt`](/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](/developers/api/v1/playground.html) 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](organization.html).