agent-studio

Launch Processor Run

Launch an execution-plane run of this processor’s newest PUBLISHED version over an uploaded document — the processor page’s “New run”.

Intake is the shared A7 path (intake.stage_agent_doc: accept-list, office→PDF staging, spreadsheets natively onto the sheet path); the staged file rides the uploaded-files machinery and launch_run resolves it via the datalab://file-{id} convention. 409 when nothing is published (drafts are a design-session concern). Returns the run summary — poll GET /runs/{id} for progress.

POST

api

agent-studio

processors

{processor_id}

runs

Launch Processor Run

import requests

url = "https://www.datalab.to/api/v1/agent-studio/processors/{processor_id}/runs"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

curl --request POST \
  --url https://www.datalab.to/api/v1/agent-studio/processors/{processor_id}/runs \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file'

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://www.datalab.to/api/v1/agent-studio/processors/{processor_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.datalab.to/api/v1/agent-studio/processors/{processor_id}/runs"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": 123,
  "processor_id": "<string>",
  "version": "<string>",
  "plane": "design",
  "status": "queued",
  "error": {
    "kind": "input",
    "message": "<string>"
  },
  "doc_name": "<string>",
  "request_id": "<string>",
  "scorecard": {},
  "check_results": [
    {
      "check_id": "<string>",
      "name": "<string>",
      "status": "pass",
      "blocking": true,
      "message": "<string>",
      "locators": [
        {
          "run_id": "<string>",
          "doc_name": "<string>",
          "surface": {
            "kind": "page",
            "label": "<string>",
            "number": 1
          },
          "block_id": "<string>",
          "cell": {
            "row": 1,
            "col": 1
          },
          "word_range": {
            "[0]": 123,
            "[1]": 123
          },
          "bbox": {
            "[0]": 123,
            "[1]": 123,
            "[2]": 123,
            "[3]": 123
          },
          "field_path": "<string>",
          "check_id": "<string>",
          "rule_id": "<string>",
          "segment": "<string>",
          "turn": 1
        }
      ]
    }
  ],
  "flag_ids": [
    123
  ],
  "token_usage": {},
  "turns": 1,
  "started": "2023-11-07T05:31:56Z",
  "finished": "2023-11-07T05:31:56Z",
  "created": "2023-11-07T05:31:56Z"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

Authorizations

X-API-Key

string

header

required

Path Parameters

processor_id

string

required

Cookies

wos-session

string

datalab_active_team

string

Body

multipart/form-data

file

required

Input PDF, image, office document (doc/docx/ppt/pptx), HTML, EPUB, or spreadsheet (xlsx/xlsm/xls/ods/csv) file. Office documents are staged to PDF at upload when possible; spreadsheets stage natively onto the per-sheet path (same intake as the design session docs upload).

Response

Successful Response

RunCard-shaped (snake_case): the drawer/board consume this.

integer

required

processor_id

string

required

Public processor id (slug).

version

string

required

Pinned version label.

plane

enum<string>

required

Available options:

design,

execution

status

enum<string>

required

Available options:

queued,

running,

done,

error

error

RunErrorResponse · object | null

Show child attributes

doc_name

string | null

request_id

string | null

APIRequest lookup key for the underlying inference request.

scorecard

Scorecard · object | null

check_results

CheckResultResponse · object[]

Show child attributes

flag_ids

integer[]

token_usage

Token Usage · object | null

turns

integer | null

Agent-loop turns the run took (the substrate result's turn count, persisted at ingest). None for runs that never reached the loop or predate the column.

Required range: x >= 0

started

string<date-time> | null

finished

string<date-time> | null

created

string<date-time> | null

Launch Processor Run

import requests

url = "https://www.datalab.to/api/v1/agent-studio/processors/{processor_id}/runs"

files = { "file": ("example-file", open("example-file", "rb")) }
headers = {"X-API-Key": "<api-key>"}

response = requests.post(url, files=files, headers=headers)

print(response.text)

curl --request POST \
  --url https://www.datalab.to/api/v1/agent-studio/processors/{processor_id}/runs \
  --header 'Content-Type: multipart/form-data' \
  --header 'X-API-Key: <api-key>' \
  --form file='@example-file'

const form = new FormData();
form.append('file', '<string>');

const options = {method: 'POST', headers: {'X-API-Key': '<api-key>'}};

options.body = form;

fetch('https://www.datalab.to/api/v1/agent-studio/processors/{processor_id}/runs', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://www.datalab.to/api/v1/agent-studio/processors/{processor_id}/runs"

	payload := strings.NewReader("-----011000010111000001101001\r\nContent-Disposition: form-data; name=\"file\"; filename=\"example-file\"\r\nContent-Type: application/octet-stream\r\n\r\n<string>\r\n-----011000010111000001101001--")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "id": 123,
  "processor_id": "<string>",
  "version": "<string>",
  "plane": "design",
  "status": "queued",
  "error": {
    "kind": "input",
    "message": "<string>"
  },
  "doc_name": "<string>",
  "request_id": "<string>",
  "scorecard": {},
  "check_results": [
    {
      "check_id": "<string>",
      "name": "<string>",
      "status": "pass",
      "blocking": true,
      "message": "<string>",
      "locators": [
        {
          "run_id": "<string>",
          "doc_name": "<string>",
          "surface": {
            "kind": "page",
            "label": "<string>",
            "number": 1
          },
          "block_id": "<string>",
          "cell": {
            "row": 1,
            "col": 1
          },
          "word_range": {
            "[0]": 123,
            "[1]": 123
          },
          "bbox": {
            "[0]": 123,
            "[1]": 123,
            "[2]": 123,
            "[3]": 123
          },
          "field_path": "<string>",
          "check_id": "<string>",
          "rule_id": "<string>",
          "segment": "<string>",
          "turn": 1
        }
      ]
    }
  ],
  "flag_ids": [
    123
  ],
  "token_usage": {},
  "turns": 1,
  "started": "2023-11-07T05:31:56Z",
  "finished": "2023-11-07T05:31:56Z",
  "created": "2023-11-07T05:31:56Z"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "input": "<unknown>",
      "ctx": {}
    }
  ]
}

compliance

API Reference

Custom Processors

Processor Templates

Custom Pipelines (Deprecated)

Pipeline Templates (Deprecated)

files

eval_rubrics

collections

pipelines

agent-studio

extraction_schemas

Launch Processor Run

Authorizations

Path Parameters

Cookies

Body

Response