> ## Documentation Index > Fetch the complete documentation index at: https://docs.connie.ai/llms.txt > Use this file to discover all available pages before exploring further. # Run a tool > Runs the tool once per `Idempotency-Key`. Connie waits up to 25 seconds: a successful call that ends sooner answers `200` with its outcome; a longer one answers `202` with `status: in_progress`, and keeps running. Then poll `GET /api/tool-invocations/{invocationId}` every few seconds, or pass `webhook` and Connie POSTs the outcome when the call ends. Sending the same request again with the same key returns the same operation (marked `replayed`) and never runs or charges a completed operation twice. A request that did not run and has `error.retryable: true` may be attempted again with the same key. ## OpenAPI ````yaml openapi/tool-api.yaml POST /api/tool/{toolId} openapi: 3.1.0 info: title: Connie Tool API version: 1.0.0 description: > Run supported tools in your Connie workspace from your own code: find a tool, read its inputs and price, run it, and get the result back in the response, by polling, or by webhook. Requests use a workspace API key (`sk_…`) and the workspace's credits. See https://docs.connie.ai/developers/tool-api. servers: - url: https://conigma-tool-server-production.up.railway.app security: - bearerKey: [] tags: - name: Tools description: Find a tool and read its exact inputs, availability and price. - name: Operations description: Run a tool, and read the outcome of a run. - name: Webhooks description: The secret that signs completion webhooks. paths: /api/tool/{toolId}: parameters: - name: toolId in: path required: true description: >- The tool's id, exactly as search returns it, URL-encoded once (a `/` becomes `%2F`). schema: type: string post: tags: - Operations summary: Run a tool description: > Runs the tool once per `Idempotency-Key`. Connie waits up to 25 seconds: a successful call that ends sooner answers `200` with its outcome; a longer one answers `202` with `status: in_progress`, and keeps running. Then poll `GET /api/tool-invocations/{invocationId}` every few seconds, or pass `webhook` and Connie POSTs the outcome when the call ends. Sending the same request again with the same key returns the same operation (marked `replayed`) and never runs or charges a completed operation twice. A request that did not run and has `error.retryable: true` may be attempted again with the same key. operationId: runTool parameters: - name: Idempotency-Key in: header required: true description: > One value per logical operation, for example a UUID you generate and keep. 8 to 200 characters: letters, digits and `. _ : ~ + / = -`. Reuse it on every retry of that operation; a new key runs the tool again. schema: type: string minLength: 8 maxLength: 200 requestBody: required: true content: application/json: schema: type: object additionalProperties: false required: - input properties: input: type: object description: The tool's inputs, as described by its `inputSchema`. additionalProperties: true webhook: type: string format: uri maxLength: 2048 description: > An https URL, at most 2,048 characters once encoded, whose host resolves to a public internet address. When the call ends, Connie POSTs a signed `tool_invocation.*` event to it. See the webhook in this reference. example: input: url: https://www.instagram.com/nasa webhook: https://example.com/connie-webhook responses: '200': description: >- The call ended within the wait and the tool succeeded (`ok: true`). A tool that ran and failed answers 400 with `tool_failed`. content: application/json: schema: $ref: '#/components/schemas/Operation' '202': description: >- The call is still running. Poll the operation, or wait for the webhook. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Operation' example: invocationId: 7c0e5a52-1f7a-4e0e-9a51-0d6b2f7d1c11 toolId: instagram-profiles-collect-by-url status: in_progress ok: false replayed: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/PaymentRequired' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '413': $ref: '#/components/responses/TooLarge' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/Unavailable' components: schemas: Operation: type: object required: - status - ok properties: invocationId: type: string format: uuid description: The operation's id. Keep it. toolId: type: string status: type: string enum: - completed - in_progress - not_executed - unknown_outcome description: > `completed`: the tool ran (`ok` says whether it succeeded). `in_progress`: still running. `not_executed`: nothing ran and nothing was charged. `unknown_outcome`: the tool may have run; do not run it again automatically. ok: type: boolean result: description: The tool's output, when `ok` is true and it is under 1 MiB. resultRef: type: object description: >- Present instead of `result` when the output is over 1 MiB. Fetch it with `?result=full`. properties: invocationId: type: string format: uuid error: $ref: '#/components/schemas/Error' billing: $ref: '#/components/schemas/BillingReceipt' replayed: type: boolean description: >- `true` when this answer repeats an earlier request with the same key. chargedThisRequest: type: number description: Credits charged by this request; 0 on a replay. recovery: type: object description: >- For media generation only: how to recover the result of an `unknown_outcome`. properties: toolId: type: string enum: - get-generation input: type: object properties: recoveryId: type: string Error: type: object required: - code - message - retryable properties: code: type: string description: Stable, for your code. See Errors and limits for the list. example: insufficient_credits message: type: string description: Written for a person; safe to show as is. retryable: type: boolean description: >- `true`: sending the same request again (same key) may succeed. `false`: stop automatic retries and follow the message. Check this field even for HTTP 503 with Retry-After. BillingReceipt: type: object required: - chargedCredits - items properties: chargedCredits: type: number description: Credits this call cost in all. items: type: array items: $ref: '#/components/schemas/BillingItem' lowBalance: type: object properties: balance: type: number message: type: string nextStep: type: string url: type: string BillingItem: type: object required: - toolId - summary - chargedCredits - status properties: toolId: type: string summary: type: string chargedCredits: type: number status: type: string enum: - charged - not_charged - refunded externalBilling: type: string enum: - may_apply description: Present when a connected app may also bill you on its own side. heldCredits: type: number description: >- Credits held for a job that has not settled yet; the unused part is returned. headers: RetryAfter: description: Seconds to wait before asking again. schema: type: integer responses: BadRequest: description: > The tool ran and failed: `tool_failed`, or `source_input_unreachable` (the link or page held nothing the tool could read; sending the same input again won't change that). Or the request was invalid and nothing ran: `invalid_input` (the input doesn't match the tool's schema), `invalid_envelope`, `invalid_json`, `invalid_content_type`, `invalid_tool_id`, `invalid_invocation_id`, `invalid_webhook`, `idempotency_key_required`. content: application/json: schema: $ref: '#/components/schemas/Operation' Unauthorized: description: >- The API key is missing, invalid, revoked or expired (`authentication_required`), or the credential is not an explicit workspace or scoped API key (`api_key_required`). content: application/json: schema: $ref: '#/components/schemas/Operation' PaymentRequired: description: >- `insufficient_credits`: the workspace has too few credits. Nothing ran and nothing was charged. content: application/json: schema: $ref: '#/components/schemas/Operation' Forbidden: description: > The key can't do this: `permission_required` (the key lacks `tools:read` or `tools:execute`), `tool_disabled`, `unsupported_context`, `execution_identity_required`, `connection_required`, `tool_forbidden` (access changed), or `tool_internal` (requires an internal context). content: application/json: schema: $ref: '#/components/schemas/Operation' NotFound: description: '`tool_not_found` or `invocation_not_found`.' content: application/json: schema: $ref: '#/components/schemas/Operation' Conflict: description: > `idempotency_conflict`: this key was already used with different input or a different webhook. `unknown_outcome`: the call may have run, but its result or credit settlement could not be confirmed; don't repeat it automatically. `replay_expired`: the stored outcome is unavailable or its 24-hour replay window expired. It will not run again. Inspect workspace usage before starting a new operation. content: application/json: schema: $ref: '#/components/schemas/Operation' TooLarge: description: '`input_too_large`: the request body is over 256 KiB.' content: application/json: schema: $ref: '#/components/schemas/Operation' RateLimited: description: > `rate_limited`: too many requests, or too many operations running or started this minute. Nothing ran. Wait for `Retry-After` and send the same request again. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Operation' Unavailable: description: > Check `error.retryable` before retrying. Temporary failures include `server_restarting`, `admission_unavailable`, `service_unavailable`, `webhooks_unavailable`, `billing_unavailable`, `not_started`, `media_model_unavailable` and `schema_unavailable`. When `error.retryable` is true, send the same request again with the same key after `Retry-After`. `feature_unavailable` (new operations disabled for this workspace) and `invalid_schema` (unsupported tool input schema) have `error.retryable: false`, even if Retry-After is present. Stop automatic retries and contact support or the tool's editor respectively. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Operation' securitySchemes: bearerKey: type: http scheme: bearer description: > A workspace API key from Settings → Developers → API keys, sent as `Authorization: Bearer sk_…` (or `X-API-Key: sk_…`). It acts as one workspace member and uses the workspace's credits. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.