API Evangelist enhancements for the Ablo API

overlay: 1.0.0
info:
  title: API Evangelist enhancements for the Ablo API
  version: 1.0.0
extends: openapi/abloatai-api-openapi.yml
x-generated: '2026-08-19'
x-method: generated
x-source: >-
  Derived from artifacts in this repo: authentication/, conventions/, errors/, rate-limits/,
  lifecycle/, plans/, mcp/ and asyncapi/. The original spec at openapi/_original/ablo-openapi.json
  is never mutated.
actions:
  - target: $.info
    description: Contact, docs and provenance the published spec omits.
    update:
      contact:
        name: Ablo Support
        email: support@abloatai.com
        url: https://www.abloatai.com
      termsOfService: https://www.abloatai.com/terms-conditions
      x-apievangelist-slug: ablo
      x-apievangelist-profile: https://apis.io/provider/ablo
      x-logo:
        url: https://www.abloatai.com/logo-black.svg
      x-error-registry: https://docs.abloatai.com/errors
      x-error-registry-codes: 288
      x-error-contract-version: '2026-08-15'
      x-llms-txt: https://docs.abloatai.com/llms.txt
      x-agents-md: https://github.com/Abloatai/abloatai/blob/main/packages/abloatai/AGENTS.md
      x-source-repository: https://github.com/Abloatai/ablo
  - target: $.externalDocs
    description: The spec ships no externalDocs.
    update:
      description: Ablo documentation
      url: https://docs.abloatai.com
  - target: $.tags
    description: The spec declares an EMPTY tags array even though all 32 operations are tagged. Declare the seven tags in use, with descriptions.
    update:
      - name: models
        description: Generic CRUD over any model the caller's pushed schema declares. The {model} path parameter is customer-defined.
      - name: claims
        description: Durable leases with a wait-line. Claims do not lock — a second writer waits and is handed the fresh row.
      - name: credentials
        description: Minting, inspecting, rotating and revoking capabilities and ephemeral session keys.
      - name: branches
        description: Immutable transaction branch planes and their expiring branch-bound credentials.
      - name: schema
        description: What the models look like on the plane this credential is bound to.
      - name: logs
        description: The ordered transaction log, and whether what was recorded could reach anyone.
      - name: commits
        description: Atomic batch operations and durable premise registration.
  - target: $.servers
    description: Annotate the two declared servers.
    update:
      - url: https://api.abloatai.com/api
        description: Production
        x-environment: production
      - url: http://localhost:8787/api
        description: Local development
        x-environment: local
        x-note: Declared by the provider; the docs do not document running the engine standalone.
  - target: $.components.securitySchemes.bearerAuth
    description: The spec's one-line description understates a five-class prefix-typed credential model.
    update:
      x-credential-classes:
        sk_: trusted runtime secret — server, worker or agent; full org authority when unscoped
        rk_: restricted or delegated runtime
        pk_: publishable browser key — read-only
        ek_: ephemeral user session — short-lived, minted server-side
        mk_: project and branch management — the only class that may carry management scopes
      x-key-grants:
        - schema:push
        - project:manage
        - branch:manage
        - organization:act-as
      x-auth-failure-header: X-Auth-Failure
      x-docs: https://docs.abloatai.com/api-keys
      x-artifact: authentication/ablo-authentication.yml
  - target: $.components.schemas.ErrorEnvelope
    description: Bind the envelope to the published 288-code registry.
    update:
      x-registry: https://docs.abloatai.com/errors
      x-registry-artifact: errors/ablo-error-codes.yml
      x-code-count: 288
      x-category-count: 14
      x-retryable-flag-published: true
      x-rfc9457: false
      x-note: Custom AbloError envelope, not application/problem+json. Every error carries a doc_url deep-link to its anchor.
  - target: $.paths['/v1/models/{model}'].get.parameters[?(@.name=='cursor')]
    description: Document the opaque cursor contract.
    update:
      x-pagination-style: cursor
      x-response-field: next_cursor
      x-replaces: starting_after
      x-renamed-in: 0.53.0
  - target: $.paths['/v1/commits'].post
    description: Flag the marquee write path and its MCP gap.
    update:
      x-idempotency-header: Idempotency-Key
      x-idempotency-retention: 24h
      x-idempotency-artifact: conventions/ablo-conventions.yml
      x-mcp-tool: null
      x-mcp-note: No MCP tool backs the atomic batch-commit operation; see mcp/ablo-tool-crosswalk.yml rest_only.
  - target: $.paths['/v1/models/{model}'].post
    description: The model write path carries idempotency in the body rather than a header.
    update:
      x-idempotency-field: idempotencyKey
      x-idempotency-note: Failed writes are NOT replayed — they re-run. Only successful writes are recorded.
      x-stale-guard-fields: [readAt, onStale, reads, track, claim]
  - target: $.paths['/v1/models/{model}/{id}/claim'].post
    description: Clarify the 201/202 split, which is the heart of the product.
    update:
      x-acquired-status: 201
      x-queued-status: 202
      x-lease-semantics: Claims do not lock. A queued writer waits for the holder and is handed the fresh row on acquisition.
      x-fence-token: fenceToken
  - target: $.info
    description: Record the surfaces the OpenAPI does not cover, so an agent reading only the spec is not misled.
    update:
      x-uncovered-surfaces:
        webhook_endpoints:
          path: /api/v1/webhook_endpoints
          documented_at: https://docs.abloatai.com/webhooks
          in_spec: false
        websocket:
          transport: WSS
          contract: none published
        projects:
          note: Project CRUD exists on the CLI and the coordination MCP server but has no operation in this spec.
        usage:
          note: Usage is visible only via X-Usage-* response headers and the get_usage MCP tool.
      x-rate-limit-artifact: rate-limits/ablo-rate-limits.yml
      x-plans-artifact: plans/ablo-plans-pricing.yml
      x-webhooks-artifact: asyncapi/ablo-webhooks.yml
      x-mcp-artifact: mcp/ablo-mcp.yml