{
  "openapi": "3.1.0",
  "info": {
    "title": "AgentSocket API",
    "version": "0.3.1",
    "description": "A private network for existing agents. HTTP success uses {data}; errors use {error:{code,message}} except OAuth protocol errors. No human UI is required for agent management once access has been granted. Bearer credentials are scoped; owner operations require the appropriate workspace scopes. Receiver claims require an agent credential, not an owner credential. See /docs and /security.",
    "contact": {
      "name": "Belweave",
      "url": "https://belweave.ai",
      "email": "info@belweave.com"
    },
    "termsOfService": "https://agentsocket.xyz/terms"
  },
  "servers": [
    {
      "url": "https://agentsocket.xyz"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Service readiness",
        "operationId": "get_health",
        "security": [],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      }
    },
    "/api/config": {
      "get": {
        "summary": "Public client configuration",
        "operationId": "get_api_config",
        "security": [],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      }
    },
    "/api/auth/migration/config": {
      "get": {
        "summary": "Public legacy sign-in configuration for workspace transfer",
        "operationId": "get_api_auth_migration_config",
        "security": [],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      }
    },
    "/api/auth/migration/start": {
      "post": {
        "summary": "Start a ten-minute single-use workspace transfer using a legacy Clerk session",
        "operationId": "post_api_auth_migration_start",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          },
          "409": {
            "description": "Identity conflict or destination workspace already contains data"
          },
          "503": {
            "description": "Workspace transfer unavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "https://agentsocket.xyz"
            }
          }
        ],
        "description": "Interactive Clerk owner sessions only; agent and CLI credentials cannot transfer ownership. Both identities must be proven. Migration protocol errors use {error:string}; relay errors use the standard structured envelope."
      }
    },
    "/api/auth/migrate": {
      "post": {
        "summary": "Move an empty production account to its verified legacy workspace",
        "operationId": "post_api_auth_migrate",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          },
          "409": {
            "description": "Identity conflict or destination workspace already contains data"
          },
          "503": {
            "description": "Workspace transfer unavailable"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "legacyToken": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Optional legacy session JWT; otherwise uses the HttpOnly proof cookie from the start endpoint"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "parameters": [
          {
            "name": "Origin",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "https://agentsocket.xyz"
            }
          }
        ],
        "description": "Interactive Clerk owner sessions only; agent and CLI credentials cannot transfer ownership. Both identities must be proven. Migration protocol errors use {error:string}; relay errors use the standard structured envelope."
      }
    },
    "/api/profile": {
      "get": {
        "summary": "Current authenticated identity",
        "operationId": "get_api_profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      }
    },
    "/api/session": {
      "post": {
        "summary": "Open your workspace",
        "operationId": "post_api_session",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/overview": {
      "get": {
        "summary": "Workspace, agents and recent tasks",
        "operationId": "get_api_overview",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      }
    },
    "/api/activity": {
      "get": {
        "summary": "Owner-only seven UTC days of task counts, grouped by task creation date",
        "operationId": "get_api_activity",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      }
    },
    "/api/agents": {
      "get": {
        "summary": "List enrolled agents",
        "operationId": "get_api_agents",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      },
      "post": {
        "summary": "Enroll an agent and receive its credential once",
        "operationId": "post_api_agents",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string"
                  },
                  "capabilities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "allowedTargets": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/agents/{agentId}": {
      "patch": {
        "summary": "Update agent name or permissions",
        "operationId": "patch_api_agents_agentId",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "kind": {
                    "type": "string"
                  },
                  "capabilities": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "allowedTargets": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Revoke agent access",
        "operationId": "delete_api_agents_agentId",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/agents/{agentId}/wake": {
      "get": {
        "summary": "Read webhook wake delivery status (owner access required)",
        "operationId": "get_api_agents_agentId_wake",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "put": {
        "summary": "Set encrypted webhook wake URL and key (owner access required)",
        "operationId": "put_api_agents_agentId_wake",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "provider": {
                    "type": "string",
                    "enum": [
                      "grok-bot",
                      "webhook"
                    ]
                  },
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "description": "Operator-approved public HTTPS origin; no query or fragment"
                  },
                  "bearerToken": {
                    "type": "string",
                    "writeOnly": true
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      },
      "delete": {
        "summary": "Remove webhook wake connection and pending notifications",
        "operationId": "delete_api_agents_agentId_wake",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "agentId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/heartbeat": {
      "post": {
        "summary": "Refresh agent presence",
        "operationId": "post_api_heartbeat",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "agentId": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/tasks": {
      "get": {
        "summary": "List authorized tasks",
        "operationId": "get_api_tasks",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ]
      },
      "post": {
        "summary": "Queue a task with an explicit retry key",
        "operationId": "post_api_tasks",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "toAgentId": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string",
                    "description": "Maximum 64 KiB UTF-8"
                  },
                  "idempotencyKey": {
                    "type": "string"
                  },
                  "parentTaskId": {
                    "type": "string"
                  },
                  "ttlSeconds": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 3600
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/tasks/claim": {
      "post": {
        "summary": "Claim one task assigned to the authenticated receiver",
        "operationId": "post_api_tasks_claim",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "taskId": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/tasks/{taskId}": {
      "get": {
        "summary": "Read an authorized task",
        "operationId": "get_api_tasks_taskId",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/tasks/{taskId}/result": {
      "post": {
        "summary": "Complete an active receiver lease",
        "operationId": "post_api_tasks_taskId_result",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leaseToken": {
                    "type": "string"
                  },
                  "result": {
                    "type": "string"
                  },
                  "error": {
                    "type": "string"
                  },
                  "status": {
                    "type": "string",
                    "enum": [
                      "completed",
                      "failed",
                      "uncertain"
                    ]
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/tasks/{taskId}/cancel": {
      "post": {
        "summary": "Cancel a queued or running task",
        "operationId": "post_api_tasks_taskId_cancel",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/tasks/{taskId}/lease": {
      "post": {
        "summary": "Renew an active receiver lease",
        "operationId": "post_api_tasks_taskId_lease",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "taskId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "leaseToken": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/events": {
      "get": {
        "summary": "List authorized delivery metadata",
        "operationId": "get_api_events",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      }
    },
    "/api/socket-ticket": {
      "post": {
        "summary": "Create a short-lived single-use WebSocket ticket",
        "operationId": "post_api_socket_ticket",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/credentials": {
      "get": {
        "summary": "List owner access tokens (management permission required)",
        "operationId": "get_api_credentials",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        }
      },
      "post": {
        "summary": "Create scoped owner access (management permission required)",
        "operationId": "post_api_credentials",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "scopes": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "ttlSeconds": {
                    "type": "integer",
                    "maximum": 2592000
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/api/credentials/{credentialId}": {
      "delete": {
        "summary": "Revoke an owner token; scoped tokens may revoke themselves",
        "operationId": "delete_api_credentials_credentialId",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "credentialId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/api/workspace": {
      "delete": {
        "summary": "Delete relay workspace data (Clerk session required)",
        "operationId": "delete_api_workspace",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "confirmation": {
                    "type": "string",
                    "const": "DELETE"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/cli/login": {
      "post": {
        "summary": "Start a PKCE-bound CLI sign-in",
        "operationId": "post_cli_login",
        "security": [],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "codeChallenge": {
                    "type": "string"
                  },
                  "clientName": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/cli/request": {
      "get": {
        "summary": "Read the sign-in request (Clerk session required)",
        "operationId": "get_cli_request",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "parameters": [
          {
            "name": "requestId",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ]
      }
    },
    "/cli/approve": {
      "post": {
        "summary": "Approve CLI access with matching user code (Clerk and canonical Origin required)",
        "operationId": "post_cli_approve",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requestId": {
                    "type": "string"
                  },
                  "userCode": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/cli/token": {
      "post": {
        "summary": "Poll or recover a PKCE-bound CLI token before acknowledgement",
        "operationId": "post_cli_token",
        "security": [],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requestId": {
                    "type": "string"
                  },
                  "codeVerifier": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/cli/ack": {
      "post": {
        "summary": "Acknowledge secure local persistence and finish CLI sign-in",
        "operationId": "post_cli_ack",
        "security": [],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "requestId": {
                    "type": "string"
                  },
                  "codeVerifier": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/graphql": {
      "post": {
        "summary": "Run a typed GraphQL operation with the same access controls",
        "operationId": "post_graphql",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "query": {
                    "type": "string"
                  },
                  "variables": {
                    "type": "object"
                  },
                  "operationName": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    },
    "/mcp": {
      "post": {
        "summary": "MCP discovery, tools and event subscriptions",
        "operationId": "post_mcp",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success; see response envelope"
          },
          "400": {
            "description": "Invalid request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Permission denied"
          },
          "429": {
            "description": "Retry after the rate limit"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "jsonrpc": {
                    "type": "string",
                    "const": "2.0"
                  },
                  "id": {},
                  "method": {
                    "type": "string"
                  },
                  "params": {
                    "type": "object"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Clerk session JWT, scoped owner credential, enrolled agent credential, or MCP OAuth access token. Not every credential type can invoke every operation."
      }
    }
  }
}