> ## Documentation Index > Fetch the complete documentation index at: https://docs.stefanbrain.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Follow the content contract in AGENTS.md. > Treat text as the canonical explanation; video and screenshots enhance it. > Do not publish unverified product behavior or duplicate an existing canonical article. # Invoke a tool synchronously (or enqueue a job for job-backed tools) ## OpenAPI ````yaml /developers/openapi/stefanbrain-v1.json post /api/developers/v1/tools/{toolName} openapi: 3.1.0 info: title: StefanBrain Developer API version: 1.0.0 description: >- REST access to StefanBrain agent runs, tools, and jobs. Authenticate with an API key from Settings → Developers. REST usage bills your prepaid API wallet at the published per-token rates (see https://docs.stefanbrain.com/developers/pricing); the MCP endpoint (/api/developers/v1/mcp, not described here) is member pricing from your plan pool. Human documentation: https://docs.stefanbrain.com/developers servers: - url: https://stefanbrain.com security: - bearerAuth: [] - apiKeyHeader: [] tags: - name: tools description: Directly invocable StefanBrain tools. - name: jobs description: Long-running tool jobs (poll for results). - name: runs description: Agentic chat runs with event streams. - name: files description: Workspace files agent runs produced in a chat. - name: media description: 'Stored Meta ad media facts: video transcripts on demand.' - name: feedback description: >- Tell StefanBrain where the API got in your way, and read the team's replies. paths: /api/developers/v1/tools/{toolName}: post: tags: - tools summary: Invoke a tool synchronously (or enqueue a job for job-backed tools) operationId: invokeTool parameters: - name: toolName in: path required: true schema: type: string - name: Idempotency-Key in: header required: false description: >- Safe blind retries on submit tools and ask_stefanbrain: resubmitting the same key within a 24-hour window (UTC day) returns the ORIGINAL job envelope — same job_id, no new work, no second charge. Injected as the idempotency_key tool argument; ignored on other tools. 1-128 chars of A-Z a-z 0-9 _ . : -; invalid values are 400 invalid_idempotency_key. schema: type: string pattern: ^[A-Za-z0-9_.:-]{1,128}$ requestBody: required: true content: application/json: schema: type: object properties: arguments: type: object description: Tool arguments matching the tool's inputSchema. additionalProperties: true chat: type: string description: Optional chat pin (chat_...). project: type: string description: Optional project pin (proj_...). additionalProperties: true responses: '200': description: Synchronous tool result. headers: x-wallet-remaining-cents: description: >- Remaining API wallet balance in USD cents after this request's pre-flight check. schema: type: integer x-wallet-resets-at: description: ISO timestamp when the wallet's monthly plan credit next resets. schema: type: string format: date-time content: application/json: schema: $ref: '#/components/schemas/ToolResult' '202': description: Job accepted (job-backed tools); poll the jobs endpoints. headers: x-wallet-remaining-cents: description: >- Remaining API wallet balance in USD cents after this request's pre-flight check. schema: type: integer x-wallet-resets-at: description: ISO timestamp when the wallet's monthly plan credit next resets. schema: type: string format: date-time content: application/json: schema: $ref: '#/components/schemas/JobAccepted' '400': description: Invalid request. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing, invalid, or revoked API key. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: >- Suspended key, missing plan access, or key scoped away from this surface (code api_key_scope_forbidden). content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: >- Unknown tool (code tool_not_found), or a tool withheld from the developer surface (code tool_not_available; the message says why). content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: >- Rate limited (codes request_per_minute, request_per_minute_user, request_per_day, user_throttled, user_suspended; Retry-After header when the limit has a reset time, plus limits, observed counts, and reset_at in the body), the runtime has no capacity to start a turn right now (code runtime_capacity_busy, Retry-After: 5), wallet exhausted (code api_wallet_exhausted), key budget exhausted (code api_key_budget_exhausted), or the plan's monthly usage pool spent for OAuth-token traffic (code monthly_usage_limit_reached). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: ToolResult: type: object description: Synchronous tool result envelope. properties: object: type: string const: tool_result request_id: type: string tool: type: string chat: type: string project: type: string is_error: type: boolean content: type: array items: type: object additionalProperties: true structured_content: type: - object - 'null' additionalProperties: true error: type: - object - 'null' description: >- Structured failure classification; an object exactly when is_error is true, null otherwise. properties: code: type: string message: type: string additionalProperties: true additionalProperties: true JobAccepted: type: object description: 202 acceptance envelope returned by job-backed tool POSTs. properties: object: type: string const: tool_job request_id: type: string tool: type: string chat: type: string project: type: string family: type: string job_id: type: string status: type: string const: queued recommended_poll_after_ms: type: - integer - 'null' status_url: type: string result_url: type: string cancel_url: type: string additionalProperties: true Error: type: object required: - error properties: error: type: object required: - message - type properties: message: type: string type: type: string enum: - invalid_request_error - authentication_error - permission_error - rate_limit_error - api_error - service_unavailable_error code: type: string additionalProperties: true additionalProperties: true securitySchemes: bearerAuth: type: http scheme: bearer description: >- Authorization: Bearer stefan_sk_... (API key — bills the API wallet) or stefan_oat_... (OAuth member token — bills your plan pool). apiKeyHeader: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.