AwrAiter Catalog API

openapi: 3.2.0
info:
  title: AwrAIter REST v1 Catalog API
  version: 1.0.0
  description: 'The MCP tool catalog over plain HTTP. One endpoint per tool: read tools answer `GET` with the arguments in the query string (also `POST` with a JSON body), write tools answer `POST` only. The body of every answer is the tool result; the HTTP status is derived from its error code. Authenticate with a personal access token or an OAuth token as `Authorization: Bearer `; the same token works for `/mcp`. Every non-2xx answer is `{ ok: false, error: { code, message } }`. The version is in the path: a breaking change ships as a new prefix, and this one keeps answering for 12 months after that with `Deprecation` and `Sunset` headers (see `x-deprecation-policy`).'
  x-deprecation-policy:
    versioning: path
    noticeMonths: 12
    headers:
    - Deprecation
    - Sunset
    - Link; rel="successor-version"
    compatible:
    - adding a tool, an optional argument, a response field, or an error code
    - widening a limit or a rate limit
    breaking:
    - removing or renaming a tool, an argument, or a response field
    - changing a field's type, a status code, or the meaning of an error code
servers:
- url: https://awraiter.ai
security:
- bearerAuth: []
tags:
- name: Catalog
  description: Self-description.
paths:
  /api/v1/tools:
    get:
      operationId: list_tools
      summary: Tool catalog
      description: Every tool available to this token with its method, path, input and output schema. A read-only token does not see write tools.
      tags:
      - Catalog
      responses:
        '200':
          description: The catalog.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ToolCatalog'
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '429':
          $ref: '#/components/responses/Error429'
components:
  responses:
    Error401:
      description: No or unknown token (`unauthorized`). The `WWW-Authenticate` header points at the OAuth resource metadata.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToolError'
    Error429:
      description: Rate limit (`rate_limited`, see `Retry-After`), AI quota (`ai_quota_exhausted`) or the daily agent-job budget (`agent_budget_exhausted`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToolError'
    Error403:
      description: Read-only token on a write tool (`read_only_token`), channel outside the team or the member's ACL (`channel_not_accessible`), channel over the plan limit (`channel_over_plan_limit`), or the user left the team (`not_team_member`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ToolError'
  schemas:
    ToolAnnotations:
      type: object
      properties:
        title:
          type: string
        readOnlyHint:
          type: boolean
        destructiveHint:
          type: boolean
        idempotentHint:
          type: boolean
        openWorldHint:
          type: boolean
      required:
      - readOnlyHint
    ToolError:
      type: object
      description: Every non-2xx answer. `code` is a stable machine-readable string shared with the MCP connector; `message` is for humans and may change. `details` is filled only for `invalid_input`.
      properties:
        ok:
          const: false
        error:
          type: object
          properties:
            code:
              type: string
            message:
              type: string
            retriable:
              type: boolean
            details:
              type: array
              items:
                type: object
                properties:
                  field:
                    type: string
                  message:
                    type: string
                required:
                - field
                - message
          required:
          - code
          - message
        usage:
          $ref: '#/components/schemas/Usage'
      required:
      - ok
      - error
    ToolCatalog:
      type: object
      properties:
        ok:
          const: true
        data:
          type: object
          properties:
            tools:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  title:
                    type: string
                  description:
                    type: string
                  method:
                    enum:
                    - GET
                    - POST
                  path:
                    type: string
                  inputSchema:
                    type: object
                  outputSchema:
                    type: object
                  annotations:
                    $ref: '#/components/schemas/ToolAnnotations'
                required:
                - name
                - description
                - method
                - path
                - inputSchema
                - annotations
          required:
          - tools
      required:
      - ok
      - data
    Usage:
      type: object
      description: Remaining paid AI actions for the team. Present only on tools that cost AI quota.
      properties:
        aiActionsRemaining:
          type: integer
          description: -1 when the team is unlimited.
        aiActionsLimit:
          type: integer
          description: -1 when the team is unlimited.
        unlimited:
          type: boolean
      required:
      - aiActionsRemaining
      - aiActionsLimit
      - unlimited
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Personal access token (`pat_…`) or OAuth 2.1 access token.