InfoLang Inc. Playground API

openapi: 3.2.0
info:
  title: InfoLang Playground 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: Playground
  description: 'Console-only affordance: run one primitive from a positional `args` envelope and get the result plus billing headers and observed latency. Session-only.'
paths:
  /v2/workspaces/{id}/playground/{op}:
    post:
      tags:
      - Playground
      summary: Run a primitive
      description: 'Runs one of `remember | recall | encode | similarity | execute` against Kairos. `args` is positional: remember/recall/encode take `args[0]` as the text/query; similarity takes `args[0]`/`args[1]`; for execute, `args` is the operations array. Non-2xx Kairos statuses are passed through with the Kairos body in `result`.'
      security:
      - sessionAuth: []
      parameters:
      - schema:
          type: string
        required: true
        name: id
        in: path
      - schema:
          type: string
          enum:
          - remember
          - recall
          - encode
          - similarity
          - execute
        required: true
        name: op
        in: path
      requestBody:
        description: Positional args envelope
        content:
          application/json:
            schema:
              type: object
              properties:
                args:
                  type: array
                  items:
                    nullable: true
                  default: []
                namespace:
                  type: string
      responses:
        '200':
          description: Kairos result plus billing headers and observed latency
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    nullable: true
                  headers:
                    type: object
                    properties:
                      tokens_saved:
                        type: number
                      overage:
                        type: number
                  latency_ms:
                    type: number
                    minimum: 0
                required:
                - headers
                - latency_ms
        '401':
          description: Missing or invalid session token
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '403':
          description: Caller lacks a grant on the workspace, or role too low. Or `lane_not_supported` — an `il_live_`/`il_test_`/`il_oauth_` credential, though valid, was presented to a route that accepts the session lane only
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        '422':
          description: Unsupported op or invalid args (gateway-side validation)
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                    required:
                    - code
                    - message
                required:
                - error
        default:
          description: Kairos non-2xx statuses (e.g. 403, 422, 503) pass through verbatim wrapped in the SAME playground envelope — `result` carries the raw Kairos body (or null if it was not JSON), not a V2 error
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    nullable: true
                  headers:
                    type: object
                    properties:
                      tokens_saved:
                        type: number
                      overage:
                        type: number
                  latency_ms:
                    type: number
                    minimum: 0
                required:
                - headers
                - latency_ms
      operationId: postV2WorkspacesByIdPlaygroundByOp
      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.'