> ## 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.

# API reference

> HTTP contracts for authenticating, inspecting tool schemas, starting Plays, and reading Play-run status.

Base URL: `https://code.deepline.com`

Call this API from a trusted backend service, serverless function, notebook, or scheduler.
Use the [CLI](https://deepline.com/docs/quickstart.md) or [SDK](https://deepline.com/docs/sdk-v2/quickstart.md) for local Play files.
These interfaces bundle and check the source before they submit it.

This page describes the shared HTTP contract.
Each [provider guide](https://deepline.com/docs/providers/google-ads-audiences/guide) describes its connection requirements and checked tool IDs.
The guide also describes required payloads, approval rules, and side effects.

## Authentication and security

Send a workspace API key with every request:

```http theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
Authorization: Bearer <DEEPLINE_API_KEY>
```

Keep the key in a server-side secret store or environment variable.
Do not send the key to a browser.
Do not commit the key to source control.
Do not include the key in a mobile application that runs on a user device.

Direct API calls use bearer authentication. They do not require separate request signatures.

## Inspect a tool before you execute it

The live contract defines tool IDs, input schemas, and Deepline prices.

1. Search for the tool.
2. Read `GET /api/v2/integrations/{toolId}/get`.
3. Check the provider guide's approval rules and side effects.

Do not derive a payload from an old blog post.
Check the outcome before you retry a provider mutation with an uncertain result.

## Inspect a public tool contract

Read the tool's schema before you execute the tool. This metadata request does not execute the tool or create a charge.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
curl --request GET \
  "https://code.deepline.com/api/v2/integrations/free_simple_company_search/get" \
  -H "Authorization: Bearer $DEEPLINE_API_KEY"
```

`free_simple_company_search` is a public, discoverable tool. Its returned
`inputSchema` describes the required `sql` field. When you deliberately execute
that tool, use the path-routed endpoint and this request envelope:

```http theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
POST /api/v2/integrations/free_simple_company_search/execute
Content-Type: application/json

{
  "payload": {
    "sql": "SELECT company_name, normalized_domain FROM companies WHERE normalized_domain = 'openai.com' LIMIT 1"
  }
}
```

New callers cannot use `POST /api/v2/integrations/execute`.
For another tool, first read `GET /api/v2/integrations/{toolId}/get`.
Then call `POST /api/v2/integrations/{toolId}/execute` with the documented input schema.

## Start a saved or prebuilt Play

Start an already saved Play with `POST /api/v2/plays/run`. Deepline-managed
prebuilt Plays must use the `prebuilt/` namespace.

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
curl --request POST "https://code.deepline.com/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/"
    }
  }'
```

This starts provider work and can use Deepline credits. The response is a
`play_run` package. Read its public run ID from `run.id`. Representative excerpt:

```json theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
{
  "schemaVersion": 1,
  "kind": "play_run",
  "run": {
    "id": "play/prebuilt/person-linkedin-to-email/run/20260829t123456-789-a1b2c3d4",
    "playName": "person-linkedin-to-email",
    "status": "running"
  }
}
```

## Read Play-run status

URL-encode `run.id`. Request the canonical run endpoint with the encoded ID:

```http theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
GET /api/v2/runs/{URL-encoded run.id}
```

For example, if the encoded ID is in `ENCODED_RUN_ID`:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
curl "https://code.deepline.com/api/v2/runs/$ENCODED_RUN_ID" \
  -H "Authorization: Bearer $DEEPLINE_API_KEY"
```

Read `run.status` from the response. `completed`, `failed`, and `cancelled` are
terminal statuses. The default response is the compact package: `outputs` and
`datasets` are package fields. Dataset rows have their own paginated endpoints.

Explicit `?full=true` selects the legacy detail wrapper. Read these fields in that response:

* `status`: the run status. `package.run.status` also contains the run status.
* `result`: the final output.
* `package.outputs`: the compact outputs.

The wrapper has no top-level `run` object.

## Environment variables

* `DEEPLINE_API_KEY`: workspace-scoped bearer key.
* Provider credentials: configure them only for the providers your workspace
  uses. Each provider guide documents its authentication requirement.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.