Runtime API Reference

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

POST /api/v2/plays/run with a saved/prebuilt name and JSON input.
Read workflowId from the response. Treat it as the public run id.
Poll GET /api/v2/runs/:runId or stream GET /api/v2/runs/:runId/tail.
Stop when status is completed, failed, or cancelled.
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

GET /api/v2/tools/search?q=... to discover ranked provider/tool candidates.
GET /api/v2/integrations/:toolId/get to inspect input schema, pricing, extractors, and examples.
POST /api/v2/integrations/:toolId/execute with payload to execute the provider-backed tool.
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.

export DEEPLINE_HOST_URL="${DEEPLINE_HOST_URL:-https://code.deepline.com}"
export DEEPLINE_API_KEY="dl_workspace_key"

Every request uses bearer auth:

Authorization: Bearer <DEEPLINE_API_KEY>

Start A Named Or Prebuilt Play

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:

{
  "workflowId": "play_run_...",
  "apiVersion": 2,
  "status": "running",
  "dashboardUrl": "https://code.deepline.com/dashboard/plays/..."
}

Poll Status

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

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

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

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<string, unknown>`	No	JSON Schema describing the tool’s input parameters.
`outputSchema`	`Record<string, unknown>`	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
`status`	`string`	Yes
`job_id`	`string`	No
`meta`	`Record<string, unknown>`	No
`toolResponse`	`{ raw: TData; meta?: TMeta; }`	Yes
`extractedLists`	`Record<string, unknown>`	No
`extractedValues`	`Record<string, unknown>`	No
`billing`	`Record<string, unknown>`	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<string, string>`	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<string, unknown>`	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<string, unknown>`	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<string, unknown>`	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<string, unknown> \| 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<string, unknown> \| 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<string, unknown>`	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<Record<string, unknown>>`	Yes	Step-level summaries emitted by the runtime.
`outputs`	`Record<string, Record<string, unknown>>`	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<string, unknown>; 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<PlayStatus>`	Yes	Get current run status by public run id.
`input`	`(runId: string) => Promise<{ runId: string; input: Record<string, unknown> \| 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<PlayRunListItem[]>`	Yes	List runs for one play, optionally filtered by status.
`tail`	`(runId: string, options?: RunsTailOptions) => Promise<PlayStatus>`	Yes	Stream run events and return the latest/terminal run status.
`logs`	`(runId: string, options?: RunsLogsOptions) => Promise<RunsLogsResult>`	Yes	Fetch persisted log lines for a run.
`exportDatasetRows`	`(input: { playName: string; tableNamespace: string; runId?: string; limit?: number; offset?: number; rowMode?: 'output' \| 'all'; }) => Promise<PlaySheetRowsResult>`	Yes	Export persisted rows for a runtime-sheet dataset/table namespace.
`stop`	`( runId: string, options?: { reason?: string }, ) => Promise<StopPlayRunResult>`	Yes	Stop a running/waiting run.
`stopAll`	`(options?: { reason?: string }) => Promise<StopAllPlayRunsResult>`	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.

​Version And Coverage

​Best Current Pattern

​Quick Call Flow

​Tool And Provider Call Flow

​Authentication

​Start A Named Or Prebuilt Play

​Poll Status

​Stream Events

​Stop A Run

​Python Caller

​Generated Route Tables

​Runtime Health

​Tool And Provider Calls

​Customer Data

​Play Runs

​Play Definitions

​Play Artifacts

​Management And CLI

​Recent Compatible API Changes

​Public Types

​ToolDefinition

​Fields

​ToolSearchOptions

​Fields

​ToolSearchResult

​Fields

​ToolExecution

​Fields

​StartPlayRunRequest

​Fields

​PlayRunStart

​Fields

​PlayStatus

​Fields

​PlayRunPackage

​Fields

​PlayRunListItem

​Fields

​StopPlayRunResult

​Fields

​RunsNamespace

​Fields

​CustomerDbQueryResult

​Fields

Version And Coverage

Best Current Pattern

Quick Call Flow

Tool And Provider Call Flow

Authentication

Start A Named Or Prebuilt Play

Poll Status

Stream Events

Stop A Run

Python Caller

Generated Route Tables

Runtime Health

Tool And Provider Calls

Customer Data

Play Runs

Play Definitions

Play Artifacts

Management And CLI

Recent Compatible API Changes

Public Types

`ToolDefinition`

Fields

`ToolSearchOptions`

Fields

`ToolSearchResult`

Fields

`ToolExecution`

Fields

`StartPlayRunRequest`

Fields

`PlayRunStart`

Fields

`PlayStatus`

Fields

`PlayRunPackage`

Fields

`PlayRunListItem`

Fields

`StopPlayRunResult`

Fields

`RunsNamespace`

Fields

`CustomerDbQueryResult`

Fields