> ## 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.
# SDK Reference
> Generated reference for Deepline play authoring primitives, runtime context methods, dataset handles, and tool result shapes.
Generated from SDK source comments by `scripts/generate-play-sdk-reference.ts`. Do not edit this file manually.
## Runtime Model
The Deepline SDK is a runtime SDK. Your TypeScript defines durable play code and typed run contracts; Deepline executes that code in the cloud runtime, records provider/tool calls, persists dataset rows, and exposes run state through SDK handles and HTTP APIs.
Use `definePlay(...)` for code that runs inside a Deepline play. Inside that function, `ctx.*` is the runtime boundary: `ctx.tools.execute` calls managed providers, `ctx.dataset` records row-level work, `ctx.step` checkpoints scalar work, `ctx.fetch` records external HTTP, and `ctx.runPlay` composes registered or prebuilt plays.
Use `Deepline.connect()` and `DeeplineClient` from regular Node/TypeScript services, scripts, schedulers, or tests. Those APIs discover tools and plays, start runs, stream/poll status, stop runs, and inspect durable output without requiring a local play file.
## Reference Map
| Area | Primary surface | Use when |
| ------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| Runtime entrypoint | `Deepline.connect()` / `DeeplineContext` | A script or service needs to call tools, run plays, or inspect runs. |
| Play authoring | `definePlay(...)` / `ctx.*` | Code should run durably inside Deepline with persisted steps, datasets, tools, and child plays. |
| Tool/provider calls | `ctx.tools.execute(...)`, `deepline.tools.execute(...)`, `client.executeTool(...)` | You need provider-backed enrichment/search with Deepline auth, billing, extraction metadata, and retries. |
| Remote plays/runs | `ctx.play(name)`, `ctx.runPlay(...)`, `PlayJob`, `client.runs` | You need to run, poll, stream, stop, export, publish, or inspect plays. |
| Raw HTTP | `references/plays-api-reference.md` | A backend, notebook, scheduler, or non-TypeScript caller invokes Deepline over REST. |
## Detail Policy
| Material | Rendered as |
| ------------------------------ | ------------------------------------------------------- |
| Tested examples | Full runnable code blocks. |
| Classes | One member table with purpose, parameters, and returns. |
| Interfaces and object types | Field tables; no duplicate declaration dump. |
| Fieldless aliases or overloads | Compact signature line plus parameter/return tables. |
| Full HTTP routes | Generated in `references/plays-api-reference.md`. |
## Tested Examples
These examples are copied from `docs-examples/sdk-v2` and validated by `bun run docs:sdk-v2:check`. Keep examples there first, then regenerate this reference.
### Run A Prebuilt From TypeScript
Source: `docs-examples/sdk-v2/run-prebuilt.ts`
```ts theme={null}
import { Deepline } from 'deepline';
const ctx = await Deepline.connect();
const job = await ctx.play('prebuilt/person-linkedin-to-email').run({
linkedin_url: 'https://www.linkedin.com/in/example-person/',
});
const result = await job.get();
console.log(JSON.stringify(result, null, 2));
```
### Define A Play With `ctx.tools.execute`
Source: `docs-examples/sdk-v2/company-lookup.play.ts`
```ts theme={null}
import { definePlay } from 'deepline';
type Input = {
domain: string;
};
type Output = {
domain: string;
lookupStatus: string;
};
export default definePlay(
'docs-company-lookup',
async (ctx, input: Input): Promise