> ## Documentation Index > Fetch the complete documentation index at: https://deepline.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Execute one provider-backed tool > Executes the named tool with a JSON payload. Authenticate with a Deepline workspace API key and inspect the tool description first. Optional Idempotency-Key binds one workspace-scoped execution to this request and caller identity; repeat the same key and input to recover or replay it. New keys authorize new executions. Keyed async calls require a declared recoverable lifecycle and completion-waiting mode; unsupported launch-only modes return 422 before dispatch. Authentication: workspace API key in `Authorization: Bearer `. The request example uses `toolId=free_simple_company_search`. Replace both the tool ID and payload for another action. Read its [tool contract](https://deepline.com/docs/api-reference/get-tool.md) first. URL-encode path values, including `/` characters inside Play references and run IDs. ## Errors | Status | Meaning | | - | - | | 400 | The request conflicts with current state or a retained request identity. | | 401 | The request conflicts with current state or a retained request identity. | | 402 | The request conflicts with current state or a retained request identity. | | 404 | The request conflicts with current state or a retained request identity. | | 409 | The request conflicts with current state or a retained request identity. | | 410 | The request conflicts with current state or a retained request identity. | | 422 | The request conflicts with current state or a retained request identity. | | 429 | The request conflicts with current state or a retained request identity. | | 500 | The request conflicts with current state or a retained request identity. | ## OpenAPI ````yaml openapi.json POST /api/v2/integrations/{toolId}/execute openapi: 3.1.1 info: title: Deepline API version: v2 description: >- Discover typed GTM tools and callable Plays, then execute a tool or start and inspect a durable Deepline Play run. Use the MCP endpoint when your client supports Model Context Protocol. contact: name: Deepline support email: team@deepline.com url: https://deepline.com/contact servers: - url: https://code.deepline.com description: Deepline production runtime API security: [] tags: - name: Health description: Availability checks. - name: Billing description: Safe recovery of existing purchase intent. - name: Tools description: Discover and execute typed provider tools. - name: Plays description: Discover, start, and inspect durable Play runs. externalDocs: description: API reference url: https://deepline.com/docs/api-reference paths: /api/v2/integrations/{toolId}/execute: post: tags: - Tools summary: Execute one provider-backed tool description: >- Executes the named tool with a JSON payload. Authenticate with a Deepline workspace API key and inspect the tool description first. Optional Idempotency-Key binds one workspace-scoped execution to this request and caller identity; repeat the same key and input to recover or replay it. New keys authorize new executions. Keyed async calls require a declared recoverable lifecycle and completion-waiting mode; unsupported launch-only modes return 422 before dispatch. operationId: executeTool parameters: - name: toolId in: path required: true description: The toolId returned by the related Deepline API call. schema: type: string minLength: 1 - name: Idempotency-Key in: header required: false description: >- Optional caller-owned execution key. Case-sensitive, 1–200 ASCII letters, digits, period, underscore, colon, or hyphen. Persist before dispatch. Changed input conflicts; expired keys cannot be reused. schema: type: string minLength: 1 maxLength: 200 pattern: ^[A-Za-z0-9._:-]+$ requestBody: required: true description: Input matching the selected tool input schema. content: application/json: schema: type: object required: - payload properties: payload: type: object description: Input matching the selected tool input schema. additionalProperties: true example: payload: sql: >- SELECT company_name, normalized_domain FROM companies WHERE normalized_domain = 'openai.com' LIMIT 1 responses: '200': description: A successful Runtime API response. content: application/json: schema: type: object properties: status: type: string job_id: type: string description: Execution request identity for billing and diagnostics. meta: type: object additionalProperties: true toolResponse: type: object properties: rawV2: description: >- Complete parsed and scrubbed provider response. Its shape is returned by the tool describe endpoint. view: enum: - data - rawV2 responseMeta: type: object additionalProperties: true required: [] extractedLists: type: object additionalProperties: true extractedValues: type: object additionalProperties: true billing: type: object properties: credits_charged: type: number cost_usd: type: number pricing_status: enum: - final - pending settlement_status: enum: - pending - queued - settled - released - requires_recovery estimated_credits: type: number estimated_cost_usd: type: number required: [] required: - status - toolResponse '400': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized '401': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized '402': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized '404': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized '409': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized '410': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized '422': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized '429': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized '500': description: >- The request conflicts with current state or a retained request identity. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: Unauthorized security: - bearerAuth: [] components: schemas: ErrorResponse: type: object required: - error properties: error: oneOf: - type: string description: Route-specific error message. - type: object properties: code: type: string message: type: string resolution: type: string additionalProperties: true securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: Deepline workspace API key description: >- Create a workspace API key in the Deepline dashboard before calling authenticated endpoints. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.