InfoLang Inc. Kairos passthrough API

openapi: 3.2.0
info:
  title: InfoLang Kairos passthrough API
  version: 2.0.0
  description: 'The InfoLang gateway. `/v2` is the console + runtime API; the raw Kairos runtime surface stays proxied at `/v1` and `/mcp`, and **Canon** — the coordination layer — at `/coord/v1` where the deployment serves it (`capabilities.canon` on `GET /v2/me`). ## Three credential lanes


    Every `/v2` request carries a bearer token, and its prefix decides the lane:


    | Lane | Credential | For |

    |---|---|---|

    | **session** (`sessionAuth`) | Supabase session JWT | the website / console |

    | **oauth** (`oauthTokenAuth`) | `il_oauth_…` | a HUMAN who connected an MCP client (Claude, an IDE) |

    | **key** (`apiKeyAuth`) | `il_live_…` / `il_test_…` | MACHINES — SDKs, servers, CI |


    The gateway verifies only the session lane, minting a separate Kairos runtime token for upstream calls; the two `il_*` credentials are classified and forwarded verbatim, and Kairos verifies them and enforces the credential↔workspace binding. ## Which lanes a route accepts


    The general rule: **anything scoped to a workspace accepts all three lanes; the routes with no workspace in the path are session-only.** Concretely —


    - **All three lanes:** the runtime ops (`Runtime`), memories and namespaces (`Memories`), `GET /v2/whoami`, the read-only `Usage` and `Activity` views, and — since credential scoping — every `/v2/workspaces/{id}/…` route: keys, members, workspace CRUD, billing, ingest, webhooks, plus `GET /v2/me`. - **Session-only:** `POST /v2/bootstrap`, the workspace collection (`GET`/`POST /v2/workspaces`), the principal-keyed `/v2/billing` routes, and the console''s playground. These answer 403 `lane_not_supported` to an `il_*` credential: with no workspace in the path there is nothing for the gateway to bind the credential to. Each route''s `security` block is authoritative. **Accepting a lane is not granting access** — an `il_*` credential also has to carry the route''s scope (below). ## Scopes


    A credential may carry LESS authority than the principal behind it. Scopes are how you say so, and they are written `resource:action`:


    - `write` on a resource implies `read` on the same resource — `memories:write` covers recall. `workspace:delete` implies nothing else. - The resources are `memories`, `coord`, `compute`, `ingest`, `usage`, `activity`, `keys`, `members`, `workspace`, `billing` and `webhooks`. `compute:read` (encode, similarity) is stateless — it touches no stored data. `coord:read`/`coord:write` cover **Canon**, the coordination layer, and are enforced by Kairos on `/coord/v1/*` rather than by the gateway. - Wildcards (`*`, `:*`, `*:read`) are accepted **when creating** a credential and are resolved right then, into the concrete set. A wildcard will NOT silently widen to cover resources InfoLang adds later; to pick up a new resource, create a new credential. - A credential can be restricted to specific workspaces and given `not_before` and/or `expires_at`. Outside `[not_before, expires_at)` it is rejected with 401 `credential_expired`. - A credential can also be restricted to specific **namespaces** — the resource axis below workspace. See below; it has consequences worth reading before you grant one. - A credential minted before scoping shipped carries no scope record and resolves to a fixed legacy default, so nothing broke when scopes arrived. Each scoped route says below whether that default covers it. ### Two ceilings


    A request is allowed only if **both** hold:


    1. the credential''s scopes permit the operation, **and**

    2. the role of the principal behind the credential permits it on that workspace (Owner > Admin > Member > ReadOnly). **Neither ceiling can raise the other.** A key carrying `keys:write` held by a principal whose role is ReadOnly cannot manage keys; equally, an Owner presenting a key scoped only to `memories:read` cannot manage keys with it.'
servers:
- url: https://api.infolang.ai
  description: Production
tags:
- name: Kairos passthrough
  description: The raw Kairos surface, proxied verbatim under /v1 and /mcp and authenticated with an API key. Request and response shapes are owned by Kairos, not by this gateway.
paths:
  /v1/remember:
    post:
      tags:
      - Kairos passthrough
      summary: Store a memory
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      requestBody:
        description: Text to remember
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  minLength: 1
                source:
                  type: string
                tags:
                  type: array
                  items:
                    type: string
                namespace:
                  type: string
              required:
              - text
      responses:
        '200':
          description: Stored (forge shape)
      operationId: postV1Remember
      x-operation-id-source: derived
  /v1/recall:
    post:
      tags:
      - Kairos passthrough
      summary: Semantic search
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      requestBody:
        description: Query
        content:
          application/json:
            schema:
              type: object
              properties:
                query:
                  type: string
                  minLength: 1
                top_k:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  default: 5
                namespace:
                  type: string
                verbose:
                  type: boolean
                properties:
                  type: object
                  additionalProperties:
                    type: object
                    properties:
                      gte:
                        type: number
                      lte:
                        type: number
                    additionalProperties: false
                golden:
                  type: boolean
                adaptive:
                  type: boolean
                format:
                  type: string
                  enum:
                  - full
                  - lossless
                  - exact
                  - snippet
                  - meta
                snippet_chars:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                margin:
                  type: number
                  minimum: 0
                queries:
                  type: array
                  items:
                    type: string
                    minLength: 1
                  maxItems: 3
              required:
              - query
      responses:
        '200':
          description: Hits with similarity scores
      operationId: postV1Recall
      x-operation-id-source: derived
  /v1/encode:
    post:
      tags:
      - Kairos passthrough
      summary: Encode text to an embedding
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      requestBody:
        description: Text to encode
        content:
          application/json:
            schema:
              type: object
              properties:
                text:
                  type: string
                  minLength: 1
              required:
              - text
      responses:
        '200':
          description: Embedding vector
      operationId: postV1Encode
      x-operation-id-source: derived
  /v1/similarity:
    post:
      tags:
      - Kairos passthrough
      summary: Similarity between two texts
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      requestBody:
        description: Text pair
        content:
          application/json:
            schema:
              type: object
              properties:
                text1:
                  type: string
                  minLength: 1
                text2:
                  type: string
                  minLength: 1
              required:
              - text1
              - text2
      responses:
        '200':
          description: Similarity score
      operationId: postV1Similarity
      x-operation-id-source: derived
  /v1/execute:
    post:
      tags:
      - Kairos passthrough
      summary: Batch operations
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      requestBody:
        description: Operations
        content:
          application/json:
            schema:
              type: object
              properties:
                operations:
                  type: array
                  items:
                    nullable: true
              required:
              - operations
      responses:
        '200':
          description: Per-operation results
      operationId: postV1Execute
      x-operation-id-source: derived
  /v1/memories:
    get:
      tags:
      - Kairos passthrough
      summary: List memories
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      parameters:
      - schema:
          type: string
        required: false
        name: namespace
        in: query
      - schema:
          type: number
          minimum: 0
          exclusiveMinimum: true
        required: false
        name: limit
        in: query
      responses:
        '200':
          description: Memory list
      operationId: getV1Memories
      x-operation-id-source: derived
  /v1/memories/{memoryId}:
    delete:
      tags:
      - Kairos passthrough
      summary: Forget a memory
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      parameters:
      - schema:
          type: string
        required: true
        name: memoryId
        in: path
      responses:
        '200':
          description: Forgotten
      operationId: deleteV1MemoriesByMemoryId
      x-operation-id-source: derived
  /mcp:
    post:
      tags:
      - Kairos passthrough
      summary: MCP JSON-RPC endpoint
      description: 'HTTP-fronted Model Context Protocol endpoint (JSON-RPC 2.0).


        **An unauthenticated request answers `401` with `WWW-Authenticate: Bearer resource_metadata="…/.well-known/oauth-protected-resource"`** — the OAuth discovery entry point (RFC 9728 §5.1). A client with no credential follows that header to the protected-resource document, then to the authorization server metadata, and runs the flow. The decision is made from the `Authorization` header alone; requests that DO carry a credential are forwarded unchanged.


        Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.'
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      requestBody:
        description: JSON-RPC 2.0 request
        content:
          application/json:
            schema:
              type: object
              properties: {}
      responses:
        '200':
          description: JSON-RPC 2.0 response
        '401':
          description: No credential presented — carries the WWW-Authenticate discovery challenge
      operationId: postMcp
      x-operation-id-source: derived
    get:
      tags:
      - Kairos passthrough
      summary: MCP event stream (streamable-HTTP transport)
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      responses:
        '200':
          description: Server-sent event stream, if supported upstream
      operationId: getMcp
      x-operation-id-source: derived
    delete:
      tags:
      - Kairos passthrough
      summary: End an MCP session (streamable-HTTP transport)
      description: Proxied verbatim to Kairos. The gateway applies NO authentication of its own here — /v1 and /mcp sit outside the /v2 middleware, so the Authorization header is forwarded untouched and Kairos is the sole authority. In practice that means either `il_*` credential is accepted (an API key, or an `il_oauth_` token — the latter is how an MCP client reaches /mcp); a Supabase session JWT is NOT, since Kairos cannot verify one. Response shapes are owned by Kairos. The gateway forwards ALL methods under /v1/* and /mcp — the operations listed here are the primary surface, not an exhaustive proxy inventory.
      security:
      - apiKeyAuth: []
      - oauthTokenAuth: []
      responses:
        '200':
          description: Session ended, if supported upstream
      operationId: deleteMcp
      x-operation-id-source: derived
components:
  securitySchemes:
    sessionAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: '**Use this when the caller is a signed-in person in the InfoLang console (the website).** Not for anything you deploy: a session token belongs to a browser session, cannot be minted programmatically, and expires with the session. For a server or CI job use `apiKeyAuth`; for an end user connecting a tool to their own workspace use `oauthTokenAuth`.


        Supabase session JWT — the website lane. Accepted on EVERY /v2 route, and the ROOT of authority: it carries no scope ceiling of its own (the caller''s role on each workspace is the only limit) and it is what mints every attenuated machine credential. The gateway verifies the session and mints a separate Kairos runtime token for upstream calls — session JWTs are never forwarded to Kairos.'
    apiKeyAuth:
      type: http
      scheme: bearer
      description: '**Use this for machines — SDKs, your backend, cron jobs, CI.** Create one per workspace in the console, restricted to the scopes that job actually needs (and, if you want, to specific workspaces and a validity window). `il_test_` and `il_live_` are separate environments. This is the credential to reach for whenever there is no human in the loop; if a human IS in the loop and connecting their own tool, use `oauthTokenAuth` instead so the action is attributed to them.


        InfoLang API key (il_live_… / il_test_…) — the machine lane, for SDKs, servers and CI. Used by the /v1 and /mcp passthrough surface and by the /v2 routes it carries the scope for; verified by Kairos, not the gateway. Authority is carried by the key — an explicit `(scopes × workspaces × TTL)` policy set at mint time and never wider than the credential that minted it. A key minted before scoping carries no policy and resolves to the named `LEGACY_DEFAULT` set (`memories:*`, `compute:read`, `usage:read`, `activity:read`, `ingest:write`, all workspaces its principal holds).'
    oauthTokenAuth:
      type: http
      scheme: bearer
      description: '**Use this when a PERSON is connecting a tool to their own workspace** — an MCP client, an IDE, a third-party app acting on their behalf. The token is issued to that person, so what it can do is bounded by their role on the workspace, and revoking the connection revokes the access. Do not ask an end user to paste an API key into a tool to achieve this; that hands the tool a machine credential and attributes its writes to whoever created the key.


        OAuth access token (il_oauth_…) — the human lane: a token issued to a PERSON who connected an MCP client (Claude, an IDE) rather than to a machine. Opaque; verified by Kairos, not the gateway. Issuance (authorization server, consent, PKCE, DCR) is a separate build — this documents the credential''s acceptance on the routes that already take it.'