{"openapi":"3.1.1","info":{"title":"Deepline Runtime 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"}},"externalDocs":{"description":"Deepline Runtime API reference","url":"https://deepline.com/docs/sdk-v2/api-reference"},"servers":[{"url":"https://code.deepline.com","description":"Deepline production runtime API"}],"tags":[{"name":"Health","description":"Availability checks."},{"name":"Tools","description":"Discover and execute typed provider tools."},{"name":"Plays","description":"Discover, start, and inspect durable Play runs."}],"paths":{"/api/v2/health":{"get":{"operationId":"getRuntimeHealth","tags":["Health"],"summary":"Check Runtime API availability","description":"Returns the current Deepline Runtime status. This endpoint does not require authentication.","responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}},"x-deepline-sdk-client-methods":["health"],"x-deepline-contract-source-files":["src/app/api/v2/health/route.ts"]}},"/api/v2/tools":{"get":{"operationId":"listTools","tags":["Tools"],"summary":"List callable provider tools","description":"Lists the current callable provider-backed tools. Set compact=false to include each tool input and output schema.","parameters":[{"name":"categories","in":"query","required":false,"description":"Comma-separated tool categories to include.","schema":{"type":"string"}},{"name":"tags","in":"query","required":false,"description":"Comma-separated tool tags to include.","schema":{"type":"string"}},{"name":"grep","in":"query","required":false,"description":"Literal terms to match against tool metadata.","schema":{"type":"string"}},{"name":"compact","in":"query","required":false,"description":"Set false to include input and output schemas.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolCatalog"}}}},"400":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-deepline-sdk-client-methods":["listTools"],"x-deepline-contract-source-files":["src/app/api/v2/tools/route.ts"]}},"/api/v2/tools/search":{"get":{"operationId":"searchTools","tags":["Tools"],"summary":"Search callable provider tools","description":"Searches the tool catalog by intent and returns ranked typed tool candidates.","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"description":"The task or capability to search for. Omit when filtering only by categories or search_terms.","schema":{"type":"string"}},{"name":"categories","in":"query","required":false,"description":"Comma-separated tool categories to filter.","schema":{"type":"string"}},{"name":"search_terms","in":"query","required":false,"description":"Comma-separated capability terms to rank and filter by, including when q is empty.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum candidates to return.","schema":{"type":"integer","minimum":1,"maximum":50,"default":20}}],"responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolSearch"}}}},"400":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-deepline-sdk-client-methods":["searchTools"],"x-deepline-contract-source-files":["src/app/api/v2/tools/search/route.ts"]}},"/api/v2/integrations/{toolId}/get":{"get":{"operationId":"getTool","tags":["Tools"],"summary":"Describe one provider-backed tool","description":"Returns the tool input schema, output schema, pricing guidance, and execution metadata. Read this before executing an unfamiliar tool.","security":[{"bearerAuth":[]}],"parameters":[{"name":"toolId","in":"path","required":true,"description":"The toolId returned by the related Deepline API call.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ToolDescription"}}}},"400":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-deepline-sdk-client-methods":["getTool"],"x-deepline-contract-source-files":["src/app/api/v2/integrations/get/route.ts"]}},"/api/v2/integrations/{toolId}/execute":{"post":{"operationId":"executeTool","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.","security":[{"bearerAuth":[]}],"parameters":[{"name":"toolId","in":"path","required":true,"description":"The toolId returned by the related Deepline API call.","schema":{"type":"string","minLength":1}}],"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}}}}}},"responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"type":"object","description":"The route-owned response envelope. Dynamic tool and Play fields are described by the discovery endpoint returned before execution.","additionalProperties":true}}}},"400":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-deepline-sdk-client-methods":["executeTool","executeToolRaw"],"x-deepline-contract-source-files":["src/app/api/v2/integrations/execute/route.ts"]}},"/api/v2/plays/run":{"post":{"operationId":"startPlayRun","tags":["Plays"],"summary":"Start a saved or prebuilt Play run","description":"Starts a durable Play run for a saved or prebuilt play name. Read run.id from the response, then poll getRun until run.status is terminal.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"description":"A saved or prebuilt Play reference with its typed input.","content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","description":"Saved or prebuilt Play reference."},"input":{"type":"object","description":"Input matching the selected Play schema.","additionalProperties":true}}}}}},"responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayRunPackage"}}}},"400":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"402":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"503":{"description":"A temporary runtime dependency is unavailable. Retry after the Retry-After response header when present.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}},"headers":{"Retry-After":{"description":"Minimum whole seconds to wait before retrying the request.","schema":{"type":"integer","minimum":1}}}}},"x-deepline-sdk-client-methods":["startPlayRun","startPlayRunFromBundle","runPlay"],"x-deepline-contract-source-files":["src/app/api/v2/plays/run/route.ts"]}},"/api/v2/plays":{"get":{"operationId":"listPlays","tags":["Plays"],"summary":"List and search callable Plays","description":"Lists saved and prebuilt Plays available to the authenticated workspace. Use search or grep to narrow by capability before starting a run.","security":[{"bearerAuth":[]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Text to match against callable Play metadata and contracts.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum Plays to return.","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}}],"responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayCatalog"}}}},"401":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-deepline-sdk-client-methods":["listPlays","searchPlays"],"x-deepline-contract-source-files":["src/app/api/v2/plays/route.ts"]}},"/api/v2/plays/{name}":{"get":{"operationId":"getPlay","tags":["Plays"],"summary":"Describe one callable Play","description":"Returns the selected Play and its callable input and output contract. Read this before starting a Play with unfamiliar input.","security":[{"bearerAuth":[]}],"parameters":[{"name":"name","in":"path","required":true,"description":"The name returned by the related Deepline API call.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Play"}}}},"401":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-deepline-sdk-client-methods":["getPlay","describePlay"],"x-deepline-contract-source-files":["src/app/api/v2/plays/[name]/route.ts"]}},"/api/v2/runs/{runId}":{"get":{"operationId":"getRun","tags":["Plays"],"summary":"Get one Play run status","description":"Returns the canonical status and completed output for one Play run.","security":[{"bearerAuth":[]}],"parameters":[{"name":"runId","in":"path","required":true,"description":"The runId returned by the related Deepline API call.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"A successful Runtime API response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlayRunPackage"}}}},"401":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"A machine-readable error with a safe recovery instruction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"x-deepline-sdk-client-methods":["runs.get","getRunStatus","getPlayStatus"],"x-deepline-contract-source-files":["src/app/api/v2/runs/[runId]/route.ts"]}}},"components":{"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."}},"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}]}}},"Health":{"type":"object","required":["status","version","timestamp"],"properties":{"status":{"type":"string","const":"ok"},"version":{"type":"string","const":"v2"},"timestamp":{"type":"string","format":"date-time"}}},"ToolCatalog":{"type":"object","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/Tool"}}},"additionalProperties":true},"ToolSearch":{"type":"object","properties":{"tools":{"type":"array","items":{"$ref":"#/components/schemas/SearchTool"}}},"additionalProperties":true},"Tool":{"type":"object","required":["toolId","provider","operationId","description"],"properties":{"toolId":{"type":"string"},"provider":{"type":"string"},"operationId":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","additionalProperties":true},"outputSchema":{"type":"object","additionalProperties":true}},"additionalProperties":true},"MonitorTool":{"type":"object","required":["toolId","provider","description","kind","callable"],"properties":{"toolId":{"type":"string"},"provider":{"type":"string"},"description":{"type":"string"},"kind":{"type":"string","enum":["monitor_type","monitor_variant_index"]},"callable":{"type":"boolean","const":false},"payload_schema":{"type":"object","additionalProperties":true},"streams":{"type":"array","items":{"type":"object"}},"variants":{"type":"array","items":{"type":"object"}}},"additionalProperties":true},"ToolDescription":{"oneOf":[{"$ref":"#/components/schemas/Tool"},{"$ref":"#/components/schemas/MonitorTool"}]},"SearchTool":{"type":"object","required":["toolId","provider","operation","description"],"properties":{"toolId":{"type":"string"},"provider":{"type":"string"},"operation":{"type":"string"},"description":{"type":"string"},"inputFields":{"type":"array","items":{"type":"string"}}},"additionalProperties":true},"PlayCatalog":{"type":"object","properties":{"plays":{"type":"array","items":{"$ref":"#/components/schemas/Play"}}},"additionalProperties":true},"Play":{"type":"object","additionalProperties":true},"PlayRunPackage":{"type":"object","required":["schemaVersion","kind","run","steps","outputs","datasets","next"],"properties":{"schemaVersion":{"type":"integer","const":1},"kind":{"type":"string","const":"play_run"},"run":{"type":"object","required":["id","playName","status"],"properties":{"id":{"type":"string"},"playName":{"type":"string"},"status":{"type":"string","enum":["queued","running","waiting","completed","failed","cancelled"]},"dashboardUrl":{"type":"string","format":"uri"}},"additionalProperties":true},"steps":{"type":"array","items":{"type":"object","additionalProperties":true}},"outputs":{"type":"object","additionalProperties":true},"datasets":{"type":"array","items":{"type":"object","additionalProperties":true}},"next":{"type":"object","additionalProperties":true}},"additionalProperties":true}}}}