Agentic Atlas Agent API

openapi: 3.2.0
info:
  title: Agentic Atlas Agent API
  description: 'Read-only JSON access to the Agentic Atlas: field-tested patterns for

    designing agentic systems — skills, subagents, plugins, and multi-agent

    workflows. **No authentication.** Every operation is public and unauthenticated. There

    is no key to obtain, no quota to register for, and no account. **Read-only.** Human operations use `GET`; `/api/agent/*` uses `POST` with

    JSON arguments to read the same Agent projection as MCP and the public CLI. Nothing here creates, updates, or deletes. Three

    consequences worth stating, because they are what a general-purpose client

    goes looking for and will not otherwise find:


    * No `Idempotency-Key`. A safe `GET` has nothing to replay-protect, so the

    header is neither required nor honoured. Retry a failed call directly. * No asynchronous jobs. Every operation answers in one round trip. There is

    no job to submit, no status to poll, and no callback to register. * No sandbox. Every operation reads published data with no key, no quota,

    and no side effect, so the live surface *is* the safe one to develop

    against — a second environment would only serve a second Release. The machine-readable form of all three is `info.x-api-shape`. **One Release at a time.** The Atlas publishes one sealed Release. Every

    reading of it carries an `X-Catalog-Revision` header naming it, and a

    refusal carries none, so take the revision off an answer and never off a

    refusal. Which is which is a property of the response, not of the status: a

    response declared with a reading''s schema is a reading whatever its status,

    and a response declared as `AtlasError` is a refusal. Today every `200` is a

    reading, and so are two `404`s, `readDecision`''s not-found miss and

    `readTour`''s unsealed walk, each declared with its own reading''s schema and

    this header; every response declared as `AtlasError` carries no revision. Two responses with the same value are guaranteed to describe the same

    Atlas. A promotion replaces the active Release wholesale rather than editing

    one in place, so a long-running client that sees the header change has

    crossed a promotion and should re-read rather than merge. **Versioning.** Addresses are stable and are not prefixed with `/v1/`; the

    protocol version travels in a header instead, so an additive change never

    moves a URL. Every API response carries `API-Version: 2`, declared on every

    response in this document with its one permitted value, and restated in

    `info.x-api-version`. The same header may be sent *on* a request to pin the

    version a client was written against: pin the version you parse, and a

    deployment serving a different one refuses with `400` instead of handing you

    a payload you will misread. Omitting it means "whatever is current", so no

    existing client has to change. This protocol version is independent of the

    content Release named by `X-Catalog-Revision`. Additive changes — a new

    operation, a new optional parameter, a new field in a response — stay within

    version 1, so parse leniently. A breaking change increments `API-Version` and is

    announced first under the policy below. **Deprecation.** A deprecated operation returns `Deprecation: true` and an

    HTTP-date `Sunset` header for at least 180 days before removal, and is

    marked `deprecated: true` in this document for that whole interval. Both

    headers are declared on every operation here so a client can read the

    retirement signal without being told where to look; both are absent while an

    operation is current. `info.x-deprecation-policy` carries the notice window,

    the two header names with their RFCs, and `deprecatedOperations` — the

    authoritative list, which is empty. No operation is deprecated today. **Human API pagination.** There is none, and that is the contract rather than a gap. Reads are *bounded*, not paged: an operation that could return many rows

    takes a `limit` whose default and maximum are declared on the parameter

    itself.'
  version: v1.1.0
  contact:
    name: Agentic Atlas
    url: https://agentic-atlas.dev/contact
    email: hello@agentic-atlas.dev
  license:
    name: Source-available; reading and use permitted, republication not
    url: https://agentic-atlas.dev/why
  x-api-version: '2'
  x-version-header: API-Version
  x-deprecation-policy:
    minimumNoticeDays: 180
    deprecationHeader: Deprecation
    deprecationHeaderSpecification: RFC 9745
    sunsetHeader: Sunset
    sunsetHeaderSpecification: RFC 8594
    deprecatedOperations: []
    versioningScheme: header
    versionHeader: API-Version
    currentVersion: '2'
    versionPinning: Optional and bidirectional. A request may state API-Version to pin the version it was written against; a value other than the current one is refused 400 rather than answered. Omitting it accepts whatever version is current.
    breakingChangePolicy: A breaking change increments the API-Version header. Additive changes — a new operation, a new optional parameter, a new response field — retain it, so a client must parse leniently.
  x-api-shape:
    readOnly: true
    methods:
    - GET
    - POST
    writeOperations: []
    authentication: none
    idempotencyKeys: Not applicable. Every operation only reads published data, so there is nothing to replay-protect; `Idempotency-Key` is neither required nor honoured. Retry a failed call directly.
    asynchronousOperations: None. Every operation answers in one round trip — no job to submit, no status to poll, no callback to register.
    sandbox: None, and none is needed. Every operation is a public read of published data with no key, no quota, and no side effect, so the live surface is the safe one to develop against.
    batchOperations:
      readCards: ids
      compare: ids
      resolveName: name
    batchStyle: 'Human batchOperations use repeated query parameters on GET; agentBatchOperations use an ids array in a JSON POST body. Each is atomic: the whole call is refused rather than partially answered, so no caller has to notice a gap in a payload that looks complete. The refusal names the id that spoiled the batch — drop it and re-batch the rest in one call. Falling back to one call per id spends a request per id to learn what the refusal already said.'
    agentBatchOperations:
      agent_cards: JSON body ids array; atomic
  x-pagination:
    appliesTo: Human GET operations; Agent POST operations declare x-pagination per operation
    style: bounded-read
    boundParameter: limit
    offsetParameter: null
    pageParameter: null
    cursorParameter: null
    nextLinkField: null
    truncationFields:
    - total
    - returned
    - truncated
    truncationReportedBy:
    - readLinks
    - readTermUsages
    description: Reads are bounded, not paged. `limit` caps one response; it does not select a window, and there is no offset, page number, or cursor to advance — no continuation state exists to carry. Ordering is the publisher's and is stable within one Release, so a bounded read is a prefix rather than a sample. Where a bound can cut, the payload reports it in-band; the remainder is reached by raising `limit` toward the maximum declared on the parameter, or by narrowing the subject. A client written for cursors should not be pointed here.
  x-availability:
    healthProbe: /healthz
    readinessProbe: /readyz
    statusDocumentation: /status
    statusPage: null
    incidentFeed: null
    slaPublished: false
    retryableStatuses:
    - 503
    description: 'Availability is best effort and no service level is promised. /healthz answers whenever the process is running and reads no database; /readyz answers 200 when this deployment can serve and 503 when it cannot, naming every check, the active Release and its Catalog revision. A 503 from an operation is the same condition and the same retry: the address is unchanged and the operation is not retired. There is no external status page, no incident feed and no uptime history — /status states each refusal this API can return with its recovery, and says that too.'
servers:
- url: https://agentic-atlas.dev
  description: The origin this API is published at
tags:


# --- truncated at 32 KB (90 KB total) ---
# Full source: https://artifacts.apis.io/agentic-atlas-dev/openapi/agentic-atlas-dev-agent-api-openapi.yml