> ## 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.
# Runtime API Reference
> Generated HTTP and SDK client reference for Deepline runtime calls: tools, provider execution, play runs, artifacts, and run inspection.
Generated from the SDK route registry and public SDK types by `scripts/generate-play-sdk-reference.ts`. Do not edit this file manually.
Generated from source comments and type declarations by `scripts/generate-play-sdk-reference.ts`. Do not edit this file manually.
## Version And Coverage
| Field | Value |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| SDK version | `0.2.0` |
| SDK HTTP API | `v2` |
| Checked-in SDK fallback | `0.2.0` |
| Minimum supported SDK | `0.1.53` |
| Deprecated below | `0.1.219` |
| Generated sources | `src/lib/sdk/api-routes.ts`
`sdk/src/types.ts`
`sdk/src/client.ts`
`sdk/src/release.ts` |
| Coverage | HTTP and SDK client surface for runtime calls: health, tool/provider discovery and execution, customer data queries, play runs, play definitions, play artifacts, files, and run inspection. |
| Not covered | Provider-specific schemas, dashboard-only UI routes, billing/auth setup guides, and tutorial prose. Provider-specific schemas are returned by the generated tool describe routes. |
## Best Current Pattern
Strong runtime API references lead with base URL, auth, version/contract metadata, language examples, and exact generated route tables. Deepline follows that shape here: use the quick call flows first, then the generated route and type tables below for contract details.
## Quick Call Flow
1. `POST /api/v2/plays/run` with a saved/prebuilt `name` and JSON `input`.
2. Read `workflowId` from the response. Treat it as the public run id.
3. Poll `GET /api/v2/runs/:runId` or stream `GET /api/v2/runs/:runId/tail`.
4. Stop when `status` is `completed`, `failed`, or `cancelled`.
5. Read final user output from `result` or the compact `package.outputs` object.
Use the CLI or TypeScript SDK for local file compilation and artifact upload. Raw HTTP is best for backend services, Python jobs, schedulers, notebooks, and warehouses that invoke an already-saved or prebuilt play.
## Tool And Provider Call Flow
1. `GET /api/v2/tools/search?q=...` to discover ranked provider/tool candidates.
2. `GET /api/v2/integrations/:toolId/get` to inspect input schema, pricing, extractors, and examples.
3. `POST /api/v2/integrations/:toolId/execute` with `payload` to execute the provider-backed tool.
4. Read normalized data from `toolResponse.raw`, `extractedValues`, and `extractedLists`. Do not expose provider spend; customer-visible billing is Deepline credits/USD only.
Inside a play, prefer `ctx.tools.execute(...)` so calls are durable, idempotent, and recorded in run progress. From a regular SDK process, use `Deepline.connect().tools.execute(...)` or `client.executeTool(...)`.
## Authentication
Use the Deepline host plus a workspace API key from a trusted backend environment.
```bash theme={null}
export DEEPLINE_HOST_URL="${DEEPLINE_HOST_URL:-https://code.deepline.com}"
export DEEPLINE_API_KEY="dl_workspace_key"
```
Every request uses bearer auth:
```http theme={null}
Authorization: Bearer
```
## Start A Named Or Prebuilt Play
```bash theme={null}
curl -X POST "$DEEPLINE_HOST_URL/api/v2/plays/run" \
-H "Authorization: Bearer $DEEPLINE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prebuilt/person-linkedin-to-email",
"input": {
"linkedin_url": "https://www.linkedin.com/in/example-person/"
}
}'
```
Response:
```json theme={null}
{
"workflowId": "play_run_...",
"apiVersion": 2,
"status": "running",
"dashboardUrl": "https://code.deepline.com/dashboard/plays/..."
}
```
## Poll Status
```bash theme={null}
curl "$DEEPLINE_HOST_URL/api/v2/runs/$WORKFLOW_ID?full=true" \
-H "Authorization: Bearer $DEEPLINE_API_KEY"
```
Terminal statuses are `completed`, `failed`, and `cancelled`. `queued`, `running`, and `waiting` are non-terminal.
## Stream Events
```bash theme={null}
curl -N "$DEEPLINE_HOST_URL/api/v2/runs/$WORKFLOW_ID/tail?mode=cli" \
-H "Authorization: Bearer $DEEPLINE_API_KEY" \
-H "Accept: text/event-stream"
```
The stream emits a canonical run snapshot first, then incremental play events until the connection closes or the run reaches terminal state.
## Stop A Run
```bash theme={null}
curl -X POST "$DEEPLINE_HOST_URL/api/v2/runs/$WORKFLOW_ID/stop" \
-H "Authorization: Bearer $DEEPLINE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"reason":"caller cancelled"}'
```
## Python Caller
This example is copied from `docs-examples/sdk-v2/http-python/run_prebuilt.py` and compiled by `bun run docs:sdk-v2:check`.
Source: `docs-examples/sdk-v2/http-python/run_prebuilt.py`
```python theme={null}
import os
import time
import json
import requests
def load_deepline_env(path=".env.deepline"):
values = {}
if not os.path.exists(path):
return values
with open(path) as env_file:
for line in env_file:
stripped = line.strip()
if not stripped or stripped.startswith("#") or "=" not in stripped:
continue
key, value = stripped.split("=", 1)
values[key.strip()] = value.strip().strip('"').strip("'")
return values
deepline_env = load_deepline_env()
BASE_URL = os.environ.get(
"DEEPLINE_HOST_URL",
deepline_env.get("DEEPLINE_HOST_URL", "https://code.deepline.com"),
)
API_KEY = os.environ.get("DEEPLINE_API_KEY", deepline_env.get("DEEPLINE_API_KEY"))
if not API_KEY:
raise RuntimeError("Missing DEEPLINE_API_KEY in .env.deepline")
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
start = requests.post(
f"{BASE_URL}/api/v2/plays/run",
headers=headers,
json={
"name": "prebuilt/person-linkedin-to-email",
"input": {
"linkedin_url": "https://www.linkedin.com/in/example-person/",
},
},
timeout=30,
)
start.raise_for_status()
workflow_id = start.json()["workflowId"]
while True:
status = requests.get(
f"{BASE_URL}/api/v2/runs/{workflow_id}",
headers=headers,
timeout=30,
)
status.raise_for_status()
body = status.json()
if body.get("status") in {"completed", "failed", "cancelled"}:
with open("person-email-result.json", "w") as f:
json.dump(body, f, indent=2)
print(body)
break
time.sleep(2)
```
## Generated Route Tables
### Runtime Health
| Method | Path | SDK/client surface | Purpose | Source |
| ------ | ---------------- | ------------------ | --------------------------------------------- | -------------------------------- |
| `GET` | `/api/v2/health` | `health` | Check API availability and SDK target health. | `src/app/api/v2/health/route.ts` |
### Tool And Provider Calls
| Method | Path | SDK/client surface | Purpose | Source |
| ------ | -------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `GET` | `/api/v2/integrations/:toolId` | `getTool` | Describe one provider-backed tool by integration id. | `src/app/api/v2/integrations/[toolId]/route.ts` |
| `POST` | `/api/v2/integrations/:toolId/execute` | `executeTool`
`executeToolRaw` | Execute one provider-backed tool call through Deepline. | `src/app/api/v2/integrations/execute/route.ts` |
| `GET` | `/api/v2/integrations/:toolId/get` | `getTool` | Describe one provider-backed tool, including schema, pricing, guidance, and extractors. | `src/app/api/v2/integrations/get/route.ts` |
| `POST` | `/api/v2/integrations/:toolId/quote` | `quoteInferenceTool` | SDK-facing route. | `src/app/api/v2/integrations/[toolId]/quote/route.ts`
`src/lib/deeplineagent/quote-service.ts`
`src/lib/deeplineagent/quote.ts` |
| `GET` | `/api/v2/integrations/list` | `searchTools` | Compatibility discovery route for integration/tool listing. | `src/app/api/v2/integrations/list/route.ts` |
| `GET` | `/api/v2/tools` | `listTools` | List callable provider/tool definitions. | `src/app/api/v2/tools/route.ts` |
| `GET` | `/api/v2/tools/providers` | `listProviders` | SDK-facing route. | `src/app/api/v2/tools/providers/route.ts` |
| `GET` | `/api/v2/tools/search` | `searchTools` | Search callable provider/tool definitions with ranked metadata search. | `src/app/api/v2/tools/search/route.ts` |
### Customer Data
| Method | Path | SDK/client surface | Purpose | Source |
| ------ | ------------------ | --------------------------------- | ---------------------------------------------------- | ---------------------------------- |
| `POST` | `/api/v2/db/query` | `db.query`
`queryCustomerDb` | Run a bounded query against the customer data plane. | `src/app/api/v2/db/query/route.ts` |
### Play Runs
| Method | Path | SDK/client surface | Purpose | Source |
| ------ | ----------------------------------- | ------------------------------------------------------------ | -------------------------------------------------------- | ---------------------------------------------------- |
| `GET` | `/api/v2/plays/:name/runs` | `listPlayRuns` | List recent runs for one play. | `src/app/api/v2/plays/[name]/runs/route.ts` |
| `GET` | `/api/v2/plays/:name/sheet` | `runs.exportDatasetRows`
`getPlaySheetRows` | Read/export runtime sheet rows for a run dataset. | `src/app/api/v2/plays/[name]/sheet/route.ts` |
| `POST` | `/api/v2/plays/run` | `startPlayRun`
`startPlayRunFromBundle`
`runPlay` | Start a saved, prebuilt, or artifact-backed play run. | `src/app/api/v2/plays/run/route.ts` |
| `GET` | `/api/v2/runs` | `runs.list`
`listRuns` | List runs with filters such as play name and status. | `src/app/api/v2/runs/route.ts` |
| `GET` | `/api/v2/runs/:runId` | `runs.get`
`getRunStatus`
`getPlayStatus` | Read canonical status, result, outputs, and run package. | `src/app/api/v2/runs/[runId]/route.ts` |
| `GET` | `/api/v2/runs/:runId/input` | `runs.input`
`getRunInput` | SDK-facing route. | `src/app/api/v2/runs/[runId]/input/route.ts` |
| `GET` | `/api/v2/runs/:runId/logs` | `runs.logs`
`getRunLogs` | SDK-facing route. | `src/app/api/v2/runs/[runId]/logs/route.ts` |
| `POST` | `/api/v2/runs/:runId/observe-grant` | `runs.tail`
`tailRun`
`runPlay` | SDK-facing route. | `src/app/api/v2/runs/[runId]/observe-grant/route.ts` |
| `POST` | `/api/v2/runs/:runId/rerun` | `runs.rerun`
`rerun` | SDK-facing route. | `src/app/api/v2/runs/[runId]/rerun/route.ts` |
| `POST` | `/api/v2/runs/:runId/stop` | `runs.stop`
`stopRun`
`cancelPlay`
`stopPlay` | Stop a running or waiting play run. | `src/app/api/v2/runs/[runId]/stop/route.ts` |
| `GET` | `/api/v2/runs/:runId/tail` | `runs.tail`
`tailRun` | Stream canonical run events over SSE. | `src/app/api/v2/runs/[runId]/tail/route.ts` |
### Play Definitions
| Method | Path | SDK/client surface | Purpose | Source |
| -------- | ----------------------------------- | ------------------------------ | ------------------------------------------- | ---------------------------------------------------- |
| `GET` | `/api/v2/plays` | `listPlays`
`searchPlays` | List or search callable plays. | `src/app/api/v2/plays/route.ts` |
| `DELETE` | `/api/v2/plays/:name` | `deletePlay` | Delete a saved org-owned play. | `src/app/api/v2/plays/[name]/route.ts` |
| `GET` | `/api/v2/plays/:name` | `getPlay`
`describePlay` | Describe a saved, shared, or prebuilt play. | `src/app/api/v2/plays/[name]/route.ts` |
| `POST` | `/api/v2/plays/:name/history/clear` | `clearPlayHistory` | SDK-facing route. | `src/app/api/v2/plays/[name]/history/clear/route.ts` |
| `POST` | `/api/v2/plays/:name/live` | `publishPlayVersion` | Promote a revision as the live named play. | `src/app/api/v2/plays/[name]/live/route.ts` |
| `GET` | `/api/v2/plays/:name/versions` | `listPlayVersions` | List saved play revisions. | `src/app/api/v2/plays/[name]/versions/route.ts` |
### Play Artifacts
| Method | Path | SDK/client surface | Purpose | Source |
| ------ | --------------------------- | ---------------------------------------------- | ---------------------------------------------------- | ------------------------------------------- |
| `POST` | `/api/v2/plays/artifacts` | `registerPlayArtifact` | Register a bundled play artifact for ad hoc runs. | `src/app/api/v2/plays/artifacts/route.ts` |
| `POST` | `/api/v2/plays/check` | `checkPlayArtifact` | Validate a play bundle before storing or running it. | `src/app/api/v2/plays/check/route.ts` |
| `POST` | `/api/v2/plays/files/stage` | `stagePlayFiles`
`resolveStagedPlayFiles` | Stage CSV or packaged files used by play runs. | `src/app/api/v2/plays/files/stage/route.ts` |
### Management And CLI
| Method | Path | SDK/client surface | Purpose | Source |
| -------- | ------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POST` | `/api/v2/auth/cli/org-create` | `org create` | SDK-facing route. | `src/app/api/v2/auth/cli/org-create/route.ts` |
| `POST` | `/api/v2/auth/cli/organizations` | `org list` | SDK-facing route. | `src/app/api/v2/auth/cli/organizations/route.ts` |
| `POST` | `/api/v2/auth/cli/register` | `auth register` | SDK-facing route. | `src/app/api/v2/auth/cli/register/route.ts` |
| `POST` | `/api/v2/auth/cli/status` | `auth status` | SDK-facing route. | `src/app/api/v2/auth/cli/status/route.ts` |
| `POST` | `/api/v2/auth/cli/switch` | `org set`
`org switch` | SDK-facing route. | `src/app/api/v2/auth/cli/switch/route.ts` |
| `GET` | `/api/v2/billing/balance` | `billing balance` | SDK-facing route. | `src/app/api/v2/billing/balance/route.ts` |
| `GET` | `/api/v2/billing/catalog/current` | `billing.plans`
`getBillingPlans`
`billing plans` | SDK-facing route. | `src/app/api/v2/billing/catalog/current/route.ts` |
| `POST` | `/api/v2/billing/checkout` | `billing checkout` | SDK-facing route. | `src/app/api/v2/billing/checkout/route.ts` |
| `POST` | `/api/v2/billing/checkout/verify` | `billing redeem` | SDK-facing route. | `src/app/api/v2/billing/checkout/verify/route.ts` |
| `POST` | `/api/v2/billing/credit-purchases` | `purchaseTargetBillingCredits` | SDK-facing route. | `src/app/api/v2/billing/credit-purchases/route.ts` |
| `GET` | `/api/v2/billing/invoices` | `billing.invoices.list`
`listBillingInvoices`
`billing invoices` | SDK-facing route. | `src/app/api/v2/billing/invoices/route.ts` |
| `GET` | `/api/v2/billing/ledger` | `billing history` | SDK-facing route. | `src/app/api/v2/billing/ledger/route.ts` |
| `DELETE` | `/api/v2/billing/limit` | `billing limit off` | SDK-facing route. | `src/app/api/v2/billing/limit/route.ts` |
| `GET` | `/api/v2/billing/limit` | `billing limit` | SDK-facing route. | `src/app/api/v2/billing/limit/route.ts` |
| `POST` | `/api/v2/billing/limit` | `billing limit set` | SDK-facing route. | `src/app/api/v2/billing/limit/route.ts` |
| `POST` | `/api/v2/billing/plan-transitions` | `transitionTargetBillingPlan` | SDK-facing route. | `src/app/api/v2/billing/plan-transitions/route.ts` |
| `GET` | `/api/v2/billing/plans` | `getTargetBillingPlans` | SDK-facing route. | `src/app/api/v2/billing/plans/route.ts` |
| `POST` | `/api/v2/billing/portal-sessions` | `createTargetBillingPortalSession` | SDK-facing route. | `src/app/api/v2/billing/portal-sessions/route.ts` |
| `GET` | `/api/v2/billing/status` | `getTargetBillingStatus` | SDK-facing route. | `src/app/api/v2/billing/status/route.ts` |
| `POST` | `/api/v2/billing/subscription/cancel` | `billing.subscription.cancel`
`cancelBillingSubscription`
`billing subscription cancel` | SDK-facing route. | `src/app/api/v2/billing/subscription/cancel/route.ts` |
| `POST` | `/api/v2/billing/subscription/checkout` | `billing subscribe` | SDK-facing route. | `src/app/api/v2/billing/subscription/checkout/route.ts` |
| `GET` | `/api/v2/billing/subscription/status` | `billing.subscription.status`
`getBillingSubscriptionStatus`
`billing subscription status` | SDK-facing route. | `src/app/api/v2/billing/subscription/status/route.ts` |
| `POST` | `/api/v2/billing/top-up` | `billing.topUp`
`topUpBillingBalance`
`billing top-up` | SDK-facing route. | `src/app/api/v2/billing/top-up/route.ts` |
| `GET` | `/api/v2/billing/usage` | `billing usage` | SDK-facing route. | `src/app/api/v2/billing/usage/route.ts` |
| `POST` | `/api/v2/cli/feedback` | `feedback` | SDK-facing route. | `src/app/api/v2/cli/feedback/route.ts` |
| `POST` | `/api/v2/cli/send-session` | `sessions send` | SDK-facing route. | `src/app/api/v2/cli/send-session/route.ts` |
| `POST` | `/api/v2/cli/send-session/chunk` | `sessions send` | SDK-facing route. | `src/app/api/v2/cli/send-session/chunk/route.ts` |
| `POST` | `/api/v2/cli/send-session/finalize` | `sessions send` | SDK-facing route. | `src/app/api/v2/cli/send-session/finalize/route.ts` |
| `POST` | `/api/v2/ingestion/repair` | `repairIngestionStorage` | SDK-facing route. | `src/app/api/v2/ingestion/repair/route.ts` |
| `GET` | `/api/v2/models/describe` | `describeModel` | SDK-facing route. | `src/app/api/v2/models/describe/route.ts`
`src/lib/deeplineagent/model-options.ts`
`src/lib/deeplineagent/generated/provider-options.ts` |
| `GET` | `/api/v2/monitors/access` | `monitors status` | SDK-facing route. | `src/app/api/v2/monitors/access/route.ts` |
| `POST` | `/api/v2/monitors/check` | `monitors check` | SDK-facing route. | `src/app/api/v2/monitors/check/route.ts` |
| `POST` | `/api/v2/monitors/deploy` | `monitors deploy` | SDK-facing route. | `src/app/api/v2/monitors/deploy/route.ts` |
| `GET` | `/api/v2/monitors/deployed` | `monitors list` | SDK-facing route. | `src/app/api/v2/monitors/deployed/route.ts` |
| `DELETE` | `/api/v2/monitors/deployed/:key` | `monitors delete` | SDK-facing route. | `src/app/api/v2/monitors/deployed/[key]/route.ts` |
| `GET` | `/api/v2/monitors/deployed/:key` | `monitors get` | SDK-facing route. | `src/app/api/v2/monitors/deployed/[key]/route.ts` |
| `PATCH` | `/api/v2/monitors/deployed/:key` | `monitors update` | SDK-facing route. | `src/app/api/v2/monitors/deployed/[key]/route.ts` |
| `POST` | `/api/v2/monitors/deployed/:key/reactivate` | `monitors reactivate` | SDK-facing route. | `src/app/api/v2/monitors/deployed/[key]/reactivate/route.ts` |
| `POST` | `/api/v2/monitors/deployed/:key/test` | `monitors test` | SDK-facing route. | `src/app/api/v2/monitors/deployed/[key]/test/route.ts` |
| `POST` | `/api/v2/monitors/deployed/:key/validate` | `monitors validate` | SDK-facing route. | `src/app/api/v2/monitors/deployed/[key]/validate/route.ts` |
| `POST` | `/api/v2/monitors/setup` | `monitors deploy (provider-specific post-deploy readback)` | SDK-facing route. | `src/app/api/v2/monitors/setup/[tool]/route.ts` |
| `GET` | `/api/v2/monitors/tools` | `monitors available` | SDK-facing route. | `src/app/api/v2/monitors/tools/route.ts` |
| `DELETE` | `/api/v2/plays/:name/share` | `unpublishSharePage` | SDK-facing route. | `src/app/api/v2/plays/[name]/share/route.ts` |
| `GET` | `/api/v2/plays/:name/share` | `getSharePage` | SDK-facing route. | `src/app/api/v2/plays/[name]/share/route.ts` |
| `PATCH` | `/api/v2/plays/:name/share` | `updateSharePage` | SDK-facing route. | `src/app/api/v2/plays/[name]/share/route.ts` |
| `POST` | `/api/v2/plays/:name/share` | `publishSharePage` | SDK-facing route. | `src/app/api/v2/plays/[name]/share/route.ts` |
| `POST` | `/api/v2/plays/:name/share/regenerate` | `regenerateSharePage` | SDK-facing route. | `src/app/api/v2/plays/[name]/share/regenerate/route.ts` |
| `POST` | `/api/v2/plays/files/stage/mint` | `stagePlayFiles`
`mintStagedPlayFileUploads` | SDK-facing route. | `src/app/api/v2/plays/files/stage/mint/route.ts` |
| `GET` | `/api/v2/sdk/compat` | `compat check` | SDK-facing route. | `src/app/api/v2/sdk/compat/route.ts` |
| `GET` | `/api/v2/secrets` | `secrets list`
`secrets check`
`listSecrets` | SDK-facing route. | `src/app/api/v2/secrets/route.ts` |
| `POST` | `/api/v2/secrets` | `secrets set` | SDK-facing route. | `src/app/api/v2/secrets/route.ts` |
| `DELETE` | `/api/v2/secrets/:id` | `secrets delete` | SDK-facing route. | `src/app/api/v2/secrets/[id]/route.ts` |
| `POST` | `/api/v2/secrets/:id/test` | `secrets test` | SDK-facing route. | `src/app/api/v2/secrets/[id]/test/route.ts` |
## Recent Compatible API Changes
These entries come from the compatible SDK/API change ledger and explain additive changes that did not require an SDK API-contract bump. Each change lives in `src/lib/sdk/compatible-changes/` so concurrent PRs do not edit a shared ledger file.
| Change | Reason |
| ------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `2026-08-play-run-input-replay` | Adds authenticated GET /api/v2/runs/:runId/input and POST /api/v2/runs/:runId/rerun routes, plus runs.input/getRunInput/runs.rerun/rerun SDK methods and deepline runs get --input / deepline runs rerun commands. These are additive capabil... |
| `2026-07-sdk-enrich-compiler-source-imports` | Resolves shared enrich-plan compiler imports through TypeScript source paths so server-side MCP callers can reuse the same compiler without relying on built JavaScript artifacts. This is an internal build-resolution change: installed CLI... |
| `2026-07-play-detached-runtime-progress` | Corrects the customer-visible status and CLI progress wording for a Play that is actively executing in a detached runtime receipt: it reports running rather than waiting, and identifies that execution state instead of incorrectly suggest... |
| `2026-07-agent-led-cli-onboarding` | Adds setup, skills, and doctor CLI commands, folder-scoped browser-auth persistence, npm-based installation guidance, and scoped update and verification behavior while retiring the separate mutable SDK shell-installer route. This is comp... |
| `2026-07-play-cost-estimates` | Adds an opt-in include\_cost\_estimates query parameter and optional costEstimate response field to GET /api/v2/plays, and adds the same optional field to GET /api/v2/plays/:name/live. This is additive and backward compatible: route paths,... |
| `2026-07-sdk-enrich-direct-tool-runtime-context` | Makes newly published deepline enrich generated plays type their legacy direct-tool helper against the existing DeeplinePlayRuntimeContext tools capability instead of an incompatible hand-written execute signature. This is a compatible l... |
| `2026-07-sdk-enrich-no-ambient-pick` | Makes newly published deepline enrich generated plays pass the existing DeeplinePlayRuntimeContext directly to their direct-tool helper instead of relying on TypeScript's ambient Pick utility type. This is a compatible local generated-so... |
| `2026-07-sdk-play-page-open-opt-in` | Makes newly published deepline plays run and enrich clients print the play page URL by default and require the new --open flag to launch a browser; the retired --no-open flag now fails loudly. The API contract is unchanged: route paths,... |
## Public Types
### `ToolDefinition`
Summary definition of a callable provider-backed tool.
Returned by `DeeplineClient.listTools` and ranked tool search. Use
`getTool(toolId)` or the matching HTTP describe route for provider-specific
schema, examples, pricing, and extraction guidance before executing.
#### Fields
| Name | Type | Required | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `toolId` | `string` | Yes | Unique tool identifier used in API calls (e.g. `"dropleads_search_people"`). |
| `provider` | `string` | Yes | Provider that backs this tool (e.g. `"hunter"`, `"dropleads"`, `"test"`). |
| `displayName` | `string` | Yes | Human-readable name for display. |
| `description` | `string` | Yes | What this tool does — suitable for LLM tool descriptions. |
| `categories` | `DeeplineToolCategory[]` | Yes | Categorization tags (e.g. `["people", "enrichment"]`). |
| `tags` | `string[]` | No | Searchable provider and account-signal tags. |
| `operation` | `string` | No | Operation slug within the provider. |
| `operationId` | `string` | No | Normalized operation identifier. |
| `operationAliases` | `string[]` | No | Alternative names that resolve to this tool. |
| `playReference` | `prebuilt/${string}` | No | Explicit globally runnable play reference for play-backed catalog entries. |
| `hasInputSchema` | `boolean` | No | Whether detailed input schema is available from `tools describe`. |
| `hasOutputSchema` | `boolean` | No | Whether detailed output schema is available from `tools describe`. |
| `inputSchema` | `Record` | No | JSON Schema describing the tool's input parameters. |
| `outputSchema` | `Record` | No | JSON Schema describing the tool's output shape. |
| `pricing` | `ToolPricingSummary \| null` | No | User-facing pricing summary. Internal provider/settlement costs are intentionally omitted. |
| `usageGuidance` | `{ execute?: string; prefer?: string[]; access?: { extractedLists?: { expression?: string; meaning?: string; }; extractedValues?: { expression?: string; meaning?: string; }; rawToolResponse?: { expression?: string; meaning?: string; }; invalidGetterHint?: string; }; toolExecutionResult?: { type?: 'ToolExecutionResult'; toolResponse?: { raw?: string; meta?: string; }; meta?: string; extractedLists?: \| Array<{ name: string; expression: string; details?: { strategy?: string; rawToolOutputPaths?: string[]; candidatePaths?: string[]; }; }> \| Record< string, { expression: string; details?: { strategy?: string; rawToolOutputPaths?: string[]; candidatePaths?: string[]; }; } >; extractedValues?: \| Array<{ name: string; expression: string; details?: { strategy?: string; rawToolOutputPaths?: string[]; candidatePaths?: string[]; }; }> \| Record< string, { expression: string; details?: { strategy?: string; rawToolOutputPaths?: string[]; candidatePaths?: string[]; }; } >; [key: string]: unknown; }; }` | No | Copyable play-runtime guidance for V2 tool execution results. |
| `search_score` | `number` | No | Search relevance score returned by ranked tool search. |
| `search_matches` | `Array<{ field: string; value: string; term?: string; }>` | No | Search match snippets returned by ranked tool search. |
| `connected` | `boolean` | No | Whether this tool is callable in the current workspace. `false` for a
bring-your-own-credential provider that has not been connected. |
| `callable` | `boolean` | No | Whether the tool can be executed. Exact lookup may return non-callable deprecated aliases. |
| `deprecated` | `boolean` | No | True when callers should migrate this exact tool id to its replacement. |
| `deprecation` | `{ replacementToolId: string; message: string; execution?: 'terminal' \| 'forward'; }` | No | Deprecation reason, replacement, and compatibility execution behavior. |
| `credentialStatus` | `\| 'managed' \| 'connected' \| 'requires_connection' \| 'deprecated'` | No | Connection status for discovery: `managed` (Deepline-run credentials),
`connected` (your own credential is connected), or `requires_connection`
(BYO provider not yet connected in this workspace). `deprecated` means
connecting credentials will not make the tool callable. |
| `requiresOwnCredential` | `boolean` | No | True when the tool requires a customer-provided credential to run. |
| `connectionMessage` | `string` | No | Actionable message shown when a connection is required. |
### `ToolSearchOptions`
Query options for ranked tool/provider discovery.
#### Fields
| Name | Type | Required | Description |
| -------------------- | -------------- | -------: | --------------------------------------------------------------------------- |
| `query` | `string` | No | Free-text search query. |
| `categories` | `string` | No | Comma-separated category filter such as `company_search` or `email_finder`. |
| `searchTerms` | `string` | No | Optional explicit search terms used by agent/CLI callers. |
| `searchMode` | `'v1' \| 'v2'` | No | Search algorithm/version. Defaults to the current ranked mode. |
| `includeSearchDebug` | `boolean` | No | Include backend debug metadata in the search response. |
### `ToolSearchResult`
Ranked tool/provider discovery response.
Includes matching tools plus render/action hints used by the CLI and agents.
#### Fields
| Name | Type | Required | Description |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------ | -------: | ------------------------------------------------------------------------------- |
| `tools` | `ToolDefinition[]` | Yes | Ranked matching tools. |
| `count` | `number` | No | Count included in this response when available. |
| `total` | `number` | No | Total available count when the backend reports it. |
| `truncated` | `boolean` | No | Whether results were truncated by server-side limits. |
| `query` | `string` | No | Echoed query. |
| `categories` | `string[]` | No | Parsed category filters. |
| `search_terms` | `string[]` | No | Parsed search terms. |
| `search_mode` | `'v1' \| 'v2'` | No | Search mode used. |
| `search_fallback_to_category` | `boolean` | No | Whether search fell back to category matching. |
| `emptyResult` | `{ reason: string; message: string; suggestions: Array<{ label: string; command: string; }>; }` | No | Explanation and next commands when filters/search succeed but match zero tools. |
| `omitted_plays_hint` | `string` | No | Hint explaining omitted play results when searching tools only. |
| `commandTemplates` | `{ describe?: string; execute?: string; }` | No | Copyable CLI command templates for follow-up discovery/execution. |
| `render` | `{ sections?: Array<{ title: string; lines: string[]; }>; actions?: Array<{ label: string; command: string; }>; }` | No | Pre-rendered sections and actions for CLI/agent display. |
### `ToolExecution`
Standard provider/tool execution envelope returned by low-level SDK calls.
`toolResponse.raw` contains the provider result. `extractedValues` and
`extractedLists` contain Deepline-normalized getters when the tool exposes
them. Billing fields are Deepline-facing and must not expose provider spend.
#### Fields
| Name | Type | Required | Description |
| ----------------- | ------------------------------- | -------: | ----------- |
| `status` | `string` | Yes | |
| `job_id` | `string` | No | |
| `meta` | `Record` | No | |
| `toolResponse` | `{ raw: TData; meta?: TMeta; }` | Yes | |
| `extractedLists` | `Record` | No | |
| `extractedValues` | `Record` | No | |
| `billing` | `Record` | No | |
### `StartPlayRunRequest`
Request body for starting a play run via `DeeplineClient.startPlayRun`.
Internal/advanced request shape for low-level submission primitives.
Most callers should prefer `deepline plays run`, `DeeplineClient.runPlay`,
or `Deepline.connect`.
Either `name` (for live plays) or `artifactStorageKey` (for packaged ad hoc runs) is required.
#### Fields
| Name | Type | Required | Description |
| --------------------- | --------------------------------------------------------------------------- | -------: | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `name` | `string` | No | Play name for registered revisions. |
| `revisionId` | `string` | No | Explicit revision ID when the caller wants a specific saved version. |
| `artifactStorageKey` | `string` | No | R2 artifact key for ad hoc artifact-backed runs. |
| `sourceCode` | `string` | No | Source snapshot already validated while registering this artifact. |
| `sourceFiles` | `Record` | No | Source graph snapshots for local helper files included in cloud preflight. |
| `description` | `string` | No | Human-readable one-line description for the revision created by file-backed runs. |
| `staticPipeline` | `unknown` | No | Static pipeline already produced while registering this artifact. |
| `artifactHash` | `string` | No | Artifact content hash already validated while registering this artifact. |
| `graphHash` | `string` | No | Static graph hash already validated while registering this artifact. |
| `runtimeArtifact` | `Record` | No | Optional preloaded artifact snapshot for immediate ad hoc execution. |
| `compilerManifest` | `PlayCompilerManifest` | No | Compiler manifest for ad hoc graph runs, including imported play dependencies. |
| `inputFileUpload` | `unknown` | No | Primary input file bytes for one-shot server-side staging. |
| `packagedFileUploads` | `unknown[]` | No | Packaged file bytes for one-shot server-side staging. |
| `input` | `Record` | No | Runtime input passed to the play function as its second argument. |
| `inputFile` | `unknown` | No | Staged file reference for the primary input file (e.g. CSV). |
| `packagedFiles` | `unknown[]` | No | Additional staged file references (dependencies, data files). |
| `force` | `boolean` | No | Compatibility flag; active sibling runs are allowed. |
| `forceToolRefresh` | `boolean` | No | Explicit cache-bypass flag for durable dataset and tool-call reuse. |
| `waitForCompletionMs` | `number` | No | Optionally let the start request wait briefly and return a terminal result. |
| `profile` | `string` | No | Per-run execution profile override. The server defaults to absurd. The
Only `absurd` is accepted; most callers should leave this unset. |
| `integrationMode` | `'live' \| 'eval_stub' \| 'fixture'` | No | Optional per-run provider execution mode for eval/smoke runs. |
| `fixtureBehavior` | `import('../../shared_libs/play-runtime/fixture-behavior').FixtureBehavior` | No | Fixture-only provider response timing and outcome simulation. |
| `runtime` | `PlayRuntimeSelection` | No | Internal runtime estate selection. The app host remains unchanged. |
| `testPolicyOverrides` | `Record` | No | Internal/dev-only runtime policy overrides for black-box durability tests. |
### `PlayRunStart`
Response from starting a play run.
Internal/advanced payload returned by low-level play submission primitives.
Most callers should prefer `deepline plays run`, `DeeplineClient.runPlay`,
or `PlayJob.get`.
#### Fields
| Name | Type | Required | Description |
| ---------------- | --------------------------------- | -------: | ----------------------------------------------------------------------------- |
| `workflowId` | `string` | Yes | Public Deepline play-run id for tracking this execution. |
| `apiVersion` | `number` | No | Public Deepline play-run API version. |
| `name` | `string` | No | Play name (echoed back from the request). |
| `status` | `string` | No | Initial status (typically `'RUNNING'`). |
| `runtimeBackend` | `string` | No | Resolved runtime backend used for this run. |
| `contract` | `Record \| null` | No | Canonical run contract compatibility metadata. |
| `dashboardUrl` | `string` | No | Dashboard URL for the named play. |
| `finalStatus` | `unknown` | No | Terminal status returned when the start request used a short completion wait. |
| `package` | `PlayRunPackage` | No | Canonical compact run package returned by current SDK/API responses. |
### `PlayStatus`
Current status of a play execution, returned by `DeeplineClient.getPlayStatus`.
Poll this until `status` reaches a terminal state:
`'completed'` | `'failed'` | `'cancelled'`.
#### Fields
| Name | Type | Required | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------: | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId` | `string` | Yes | Public play-run identifier. |
| `apiVersion` | `number` | No | Public Deepline play-run API version. |
| `name` | `string` | No | Saved play name for this run, when available. |
| `revisionId` | `string` | No | Exact saved revision launched for this run, when applicable. |
| `playName` | `string` | No | Alias for `name` used by run/result APIs. |
| `dashboardUrl` | `string` | No | Dashboard URL for inspecting the play and its run output in the app. |
| `status` | `\| 'queued' \| 'running' \| 'waiting' \| 'completed' \| 'failed' \| 'cancelled'` | Yes | Product-level play-run state. |
| `progress` | `PlayProgressStatus` | No | Execution progress with logs and error details. |
| `result` | `unknown` | No | Partial or final result. Available once the play returns. |
| `package` | `PlayRunPackage` | No | Compact typed run package returned by current run status endpoints. |
| `outputs` | `PlayRunPackage['outputs']` | No | Compact typed output summaries, mirrored from the run package when present. |
| `run` | `{ id?: string; startTime?: string \| null; closeTime?: string \| null; [key: string]: unknown; } \| null` | No | Scheduler-backed run metadata when returned by the status endpoint. |
| `resultView` | `unknown` | No | Server-rendered result view metadata for CLI/UI summaries. |
| `contract` | `Record \| null` | No | Canonical run contract snapshot metadata, when available. |
| `wait` | `{ kind: 'integration_event' \| 'sleep'; boundaryId?: string; eventKey?: string; until?: number; } \| null` | No | If the run is blocked on a durable boundary, expose the public wait state. |
| `next` | `PlayRunPackage['next'] \| Record` | No | Structured follow-up actions for inspect/query/export. |
| `failedLogs` | `{ runId: string; totalCount: number; returnedCount: number; firstSequence: number \| null; lastSequence: number \| null; truncated: boolean; hasMore: boolean; entries: string[]; view?: 'failed'; association?: 'terminal_failure_window' \| 'retained_before_truncation'; warning?: string; next?: { logs: string }; logsTruncated?: boolean; }` | No | Bounded terminal-failure log window requested by `runs.get`. |
| `rerunCommand` | `string` | No | Exact ordinary `plays run` command that can rerun a failed execution. |
| `billing` | `RunBillingSummary` | No | Projected settled-charge billing for the run. Returned by `runs.get`.
`totalCredits`/`providerEvents` describe THIS run only; `rollup` (present
with `--full`) carries the true subtree cost including ctx.runPlay children.
Deepline credits only — provider spend is never exposed. |
| `billingTotalCreditsRollup` | `number` | No | True subtree cost in Deepline credits (this run + every descendant run),
mirrored to the top level for convenience. Present only with `--full`. |
| `billingChildCredits` | `number` | No | Deepline credits attributable to descendant runs only. Present with `--full`. |
| `billingRollupIncomplete` | `boolean` | No | True when the child-run billing rollup could not be fully resolved. |
| `childRuns` | `ChildRunSummary[]` | No | Durable summaries of ctx.runPlay children, returned by `runs.get --full`. |
### `PlayRunPackage`
Compact canonical package for an inspected play run.
This object is designed for SDK/CLI/API consumers that need stable run
metadata, output handles, and follow-up actions without reading dashboard
internals.
#### Fields
| Name | Type | Required | Description |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------: | -------------------------------------------------------------------------------------------- |
| `schemaVersion` | `1` | Yes | Package schema version. |
| `kind` | `'play_run'` | Yes | Package discriminator. |
| `run` | `{ id: string; playName: string; status: string; dashboardUrl?: string; updatedAt?: number \| null; startedAt?: number \| null; finishedAt?: number \| null; durationMs?: number \| null; error?: string; activity?: PlayRunActivityProjection \| null; }` | Yes | Run identity, status, timing, and dashboard metadata. |
| `warnings` | `string[]` | No | Bounded customer-safe warnings about output projection or availability. |
| `steps` | `Array>` | Yes | Step-level summaries emitted by the runtime. |
| `outputs` | `Record>` | Yes | Named output summaries, including dataset handles and scalar outputs. |
| `datasets` | `Array<{ kind: 'dataset'; datasetId?: string; path: string; tableNamespace?: string; rowCount?: number; sqlTableName?: string; sqlQualifiedTableName?: string; recovered?: true; exportUnavailable?: { reason: 'empty_dataset' \| 'shared_table_namespace'; message: string; }; preview?: Record; actions?: PlayRunDatasetActions; }>` | No | Every durable Dataset Handle explicitly registered by this run. |
| `logs` | `{ tail: string[]; totalCount: number; returnedCount: number; truncated?: boolean; }` | No | Small retained tail of customer and runtime logs; fetch the full stream through `runs.logs`. |
| `next` | `{ inspect?: PlayRunActionPackage; full?: PlayRunActionPackage; billing?: PlayRunActionPackage; export?: PlayRunActionPackage; query?: PlayRunActionPackage; logs?: PlayRunActionPackage; }` | No | Follow-up actions a caller can perform against the run. |
### `PlayRunListItem`
Summary of a single play run, returned by `DeeplineClient.listPlayRuns`.
#### Fields
| Name | Type | Required | Description |
| ------------------------- | -------------------------------------------------------------- | -------: | --------------------------------------------------------------------------------------- |
| `workflowId` | `string` | Yes | Public Deepline play-run id. |
| `playName` | `string \| null` | No | Saved play name for this run, when available. |
| `runId` | `string` | Yes | Backend run attempt id, when exposed. |
| `parentRunId` | `string \| null` | No | Parent play-run id when this run was launched through ctx.runPlay. |
| `rootRunId` | `string \| null` | No | Root play-run id for nested ctx.runPlay descendants. |
| `type` | `string` | Yes | Workflow type (typically `'Workflow'`). |
| `status` | `string` | Yes | Human-readable status (e.g. `'Completed'`, `'Failed'`). |
| `startTime` | `string \| null` | No | ISO 8601 timestamp when the run started. |
| `startedAt` | `number \| string \| null` | No | Unix epoch milliseconds when the run started, returned by normalized V2 run summaries. |
| `closeTime` | `string \| null` | No | ISO 8601 timestamp when the run finished. |
| `finishedAt` | `number \| string \| null` | No | Unix epoch milliseconds when the run finished, returned by normalized V2 run summaries. |
| `executionTime` | `string \| null` | Yes | Duration string (e.g. `'2.5s'`). |
| `billingTotalCredits` | `number` | No | Total Deepline credits charged for the run, when available. |
| `billingMaxCreditsPerRun` | `number \| null` | No | Configured per-run Deepline credit cap, when available. |
| `memo` | `{ orgId: string; playName: string; userId: string \| null; }` | Yes | Metadata attached to the workflow. |
### `StopPlayRunResult`
Result returned by `DeeplineClient.stopPlay`.
#### Fields
| Name | Type | Required | Description |
| --------------------- | --------- | -------: | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId` | `string` | Yes | Public play-run identifier the stop request targeted. |
| `stopped` | `boolean` | Yes | Whether the server confirmed the run was stopped. |
| `hitlCancelledCount` | `number` | Yes | Number of open HITL interactions marked cancelled. |
| `staleSchedulerState` | `boolean` | No | True when the scheduler state for the run was stale and the stop could
not be confirmed. Absent on older servers (treated as confirmed). |
| `error` | `string` | No | Server-side error detail when the stop was not confirmed. |
### `RunsNamespace`
Public runs namespace exposed as `client.runs`.
This namespace mirrors the canonical `/api/v2/runs` resource family and is
the preferred low-level surface for polling, streaming, stopping, reading
logs, and exporting durable dataset rows.
#### Fields
| Name | Type | Required | Description |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------: | ------------------------------------------------------------------------ |
| `get` | `(runId: string, options?: RunsGetOptions) => Promise` | Yes | Get current run status by public run id. |
| `input` | `(runId: string) => Promise<{ runId: string; input: Record \| unknown[]; bytes: number; sha256: string \| null; replayedFromRunId: string \| null; }>` | Yes | Explicitly read the retained original input (may include customer data). |
| `rerun` | `(runId: string) => Promise<{ runId: string; replayedFromRunId: string; revisionId: string \| null; status: string; next: { inspect: string; input: string }; }>` | Yes | Start a fresh run from a prior run's retained input and pinned revision. |
| `list` | `(options: RunsListOptions) => Promise` | Yes | List runs for one play, optionally filtered by status. |
| `tail` | `(runId: string, options?: RunsTailOptions) => Promise` | Yes | Stream run events and return the latest/terminal run status. |
| `logs` | `(runId: string, options?: RunsLogsOptions) => Promise` | Yes | Fetch persisted log lines for a run. |
| `exportDatasetRows` | `(input: { playName: string; tableNamespace: string; runId?: string; limit?: number; offset?: number; rowMode?: 'output' \| 'all'; }) => Promise` | Yes | Export persisted rows for a runtime-sheet dataset/table namespace. |
| `stop` | `( runId: string, options?: { reason?: string }, ) => Promise` | Yes | Stop a running/waiting run. |
| `stopAll` | `(options?: { reason?: string }) => Promise` | Yes | Stop active runs across the current workspace. |
### `CustomerDbQueryResult`
Result returned by `DeeplineClient.db.query`.
Rows are intentionally untyped because the schema depends on the caller's SQL
query and selected customer tables.
#### Fields
| Name | Type | Required | Description |
| -------------------- | --------------------------------------------- | -------: | ----------------------------------------------------------------------------- |
| `scope` | `{ kind: 'database'; mutability: 'current' }` | No | This query reads the current mutable customer database, not one run snapshot. |
| `command` | `string` | Yes | Database command executed by the query endpoint. |
| `row_count` | `number \| null` | Yes | Total affected row count when reported by the database. |
| `row_count_returned` | `number` | Yes | Number of rows included in this response. |
| `truncated` | `boolean` | Yes | Whether server-side row limits truncated the result. |
| `columns` | `CustomerDbColumn[]` | Yes | Column metadata for the returned rows. |
| `rows` | `unknown[]` | Yes | Result rows. |