> ## 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. # Get a tool > The tool's input schema (JSON Schema), whether this key can run it, whether it needs a connected account, and its price. Reading a tool is free and runs nothing. ## OpenAPI ````yaml openapi/tool-api.yaml GET /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 get: tags: - Tools summary: Get a tool description: > The tool's input schema (JSON Schema), whether this key can run it, whether it needs a connected account, and its price. Reading a tool is free and runs nothing. operationId: getTool responses: '200': description: The tool. content: application/json: schema: $ref: '#/components/schemas/ToolDetail' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/Unavailable' components: schemas: ToolDetail: allOf: - $ref: '#/components/schemas/ToolSummary' - type: object properties: inputSchema: type: object description: JSON Schema of `input`. outputSchema: type: object description: JSON Schema of `result`, when the tool declares one. connection: type: object description: >- Whether the tool needs a connected account, and whether this key's member has one. properties: required: type: boolean configured: type: boolean reason: type: string pricing: type: object description: >- What a run costs in credits. `credits` is the usual price; `maximumCredits` the ceiling of a variable one. properties: model: type: string credits: type: - number - 'null' maximumCredits: type: - number - 'null' runtime: type: object properties: version: type: integer publicEndpoint: type: string example: /api/tool/{encodedToolId} idempotencyHeader: type: string example: Idempotency-Key ToolSummary: type: object required: - id - name - description - availability properties: id: type: string example: instagram-profiles-collect-by-url name: type: string description: type: string availability: $ref: '#/components/schemas/Availability' 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 Availability: type: object required: - status properties: status: type: string enum: - available - requires_context - unavailable description: >- `available`: this key can run it. The other two come with a `code` and a `reason` to show. code: type: string reason: 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. 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' 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' 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' headers: RetryAfter: description: Seconds to wait before asking again. schema: type: integer 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.