Eos API v1

The Eos API v1 is the target contract for private, organization-specific integrations. It gives licensed API Clients programmatic access to Eos records, Agents, conversations, reports, and events while applying the same Eos Role and business-rule fences used throughout the product.

Status: Design target. These endpoints are not available until the corresponding v1 implementation is released. Existing internal /api/** application routes are not part of this contract.

Design goals

• A stable API at https://api.eoshq.com/v1 that is independent of Eos frontend routes.
• Private API Clients created and controlled by an Eos organization administrator.
• OAuth 2.0 Client Credentials authentication for confidential server applications.
• Organization-wide record access constrained by the API Client's assigned Eos Roles.
• Deterministic authorization for direct API operations, Agent Skills, and Eos Chat.
• Machine-readable schemas, predictable errors, idempotent writes, and auditable execution.
• A contract suitable for developers and coding LLMs without requiring an MCP server.

Supported API families

APIs deliberately excluded from v1

The first version does not expose:

• API Client, license, billing, subscription, or organization-owner management.
• Provider administration or Eos operator functions.
• User impersonation.
• Agent creation, compilation, blueprint internals, or scheduling.
• Raw model prompts, chain-of-thought, internal routing, or unsanitized runtime logs.
• Personal Gmail, calendar, Slack, Microsoft, or other member-scoped provider credentials.
• Creation of new object types. Eos supports custom fields on existing objects, not custom objects.
• Formal approval decisions made by an API Client.
• Internal schedulers, Cloud Tasks handlers, provider callbacks, or existing internal application endpoints.

Authentication model

Each API Client is a licensed, non-human Eos principal fixed to one organization. It receives a Regular or Manager license and one or more permitted Eos Roles.

Admin, Owner, provider, and internal Roles cannot be assigned to API Clients. Business and Enterprise organizations include one Manager-level API Client. Every additional API Client consumes an additional Regular or Manager license selected by the administrator.

Authentication uses the OAuth 2.0 Client Credentials grant with the coarse eos.api scope. Business permissions do not come from OAuth scopes; they come from the API Client's current Eos license, Roles, module access, metadata policy, and workflow rules.

See Authentication and API Clients.

Authorization model

An API Client has organization-wide record visibility only where its Eos Roles permit the object and operation. Project membership and assignment-based row filters do not restrict the client, but the following still apply:

• License validity and organization subscription status.
• Eos Role and Skill role fences.
• Object, field, module, and metadata access.
• Workflow state, required confirmation, and business validation.
• Principal-type restrictions that prohibit billing, security, licensing, and control-plane administration.

Changing a client's Roles or disabling its license takes effect without credential rotation.

Member subjects and “my” operations

An Agent run, conversation, or supported operation may identify a member subject:

{
  "subject": {
    "member_id": "alice@example.com"
  }
}

An Eos member ID is the member's normalized email address; v1 does not invent a second opaque identifier for a member. The API Client remains the actor, and the member is only the subject. Subject selection never grants the member's permissions, uses the member's personal provider tokens, or records the action as performed by that member.

Each operation and Skill must explicitly declare whether it accepts a member subject.

Request conventions

Base URL

https://api.eoshq.com/v1

Headers

Authorization: Bearer ACCESS_TOKEN
Accept: application/json
Content-Type: application/json
X-Client-Request-Id: your-correlation-id
Idempotency-Key: required-for-supported-writes

Eos returns X-Request-Id on every request. Include it in support requests.

JSON and names

• Request and response field names use snake_case.
• IDs are opaque strings and must not be parsed.
• Timestamps use RFC 3339 UTC strings, for example 2026-08-22T10:30:00Z.
• Date-only business fields use YYYY-MM-DD.
• Money uses decimal strings plus ISO 4217 currency codes; never binary floating point.
• Unknown response fields must be ignored to allow additive evolution.

List envelopes

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

List endpoints accept limit and after. The default limit is 50 and the maximum is 200 unless a page states otherwise. Cursors are opaque.

Filtering and sorting

Filters use explicit query parameters documented by each API. sort accepts a supported field name and order is asc or desc. Unsupported filters return a validation problem; they are never silently ignored.

Optimistic concurrency

Mutable resources return an ETag. Updates to an existing resource accept If-Match. A stale version returns 412 Precondition Failed.

Idempotency

Every POST documented as idempotent accepts Idempotency-Key. The key is scoped to the API Client and operation. Reusing a key with different input returns 409 Conflict. Eos retains keys for at least 24 hours.

Asynchronous operations

Long-running operations return 202 Accepted with a Run or job resource. Clients may poll, use server-sent events, or subscribe to webhooks.

Errors

Errors use application/problem+json:

{
  "type": "https://eoshq.com/problems/role-not-permitted",
  "title": "Role does not permit this operation",
  "status": 403,
  "detail": "The Finance Role is required to send this invoice.",
  "code": "ROLE_NOT_PERMITTED",
  "request_id": "req_01J8Q5A0MRV6Q7T1YVZ45JDF3P"
}

Common statuses are 400, 401, 403, 404, 409, 412, 422, 429, and 500. Human-readable detail is not a stable programmatic contract; clients should branch on status and code.

The initial default limit is 600 authenticated API calls per API Client per minute. Token requests are limited to 30 attempts per Client ID and source address per minute. Eos may apply tighter operation-specific safety limits later. Every counted response includes RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset; a 429 also includes Retry-After.

Versioning and compatibility

• /v1 is the compatibility boundary.
• Adding optional fields, enum values, endpoints, and webhook types is non-breaking.
• Removing or changing required fields, semantics, or authorization is breaking.
• Breaking changes require a new major API version.
• Deprecated operations receive published migration guidance and a sunset date.
• Each response may include additive fields before documentation consumers update.

Audit identity

Every mutation records the API Client as actor:

{
  "actor": {
    "type": "api_client",
    "id": "apic_01J8Q4W9N0TS9AF1CXY6J5KX2F",
    "name": "Salesforce project synchronizer"
  },
  "subject_member_id": "alice@example.com",
  "source": "eos_api_v1",
  "request_id": "req_01J8Q5A0MRV6Q7T1YVZ45JDF3P"
}

The member subject is omitted when none applies.

OpenAPI and LLM use

The eventual OpenAPI document must describe exactly the operations in this linked set. It will use stable operationId values, complete examples, OAuth security declarations, error schemas, and Eos extensions for required Roles, supported principal types, side effects, and idempotency.

For coding LLMs:

• Use the Markdown link at the top of each page for clean context.
• Provide only the relevant domain page plus this overview when possible.
• Do not ask a model to infer undocumented fields or internal endpoints.
• Validate generated integrations against the Eos sandbox before production use.

Continue with Authentication and API Clients.