Fetch

POST

/v1/fetch

const url = 'https://router.telem.ai/v1/fetch';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"session_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","urls":["example"],"options":{"providers":["example"],"inline_content":true,"inline_max_chars":1,"content_format":"markdown","tier":"minimalist","max_age_seconds":1,"no_cache":true},"metadata":{}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://router.telem.ai/v1/fetch \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "session_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "urls": [ "example" ], "options": { "providers": [ "example" ], "inline_content": true, "inline_max_chars": 1, "content_format": "markdown", "tier": "minimalist", "max_age_seconds": 1, "no_cache": true }, "metadata": {} }'

Read whole pages by URL, several per call. Individual limits — the per-call URL cap among them — are set by the deployment; see Parameters & Configuration.

Authorizations

HTTPBearer

Request Body^required

application/json

FetchRequest

object

session_id

Any of:

string
null

string format: uuid

urls

required

Urls

Array<string>

options

Any of:

FetchOptions
null

FetchOptions

Typed replacement for the metadata.web_fetch grab-bag. max_urls is deliberately absent — the server cap is the cap (spec 2026-08-03).

object

providers

Any of:

Array<string>
null

Array<string>

>= 1 items

inline_content

Any of:

boolean
null

boolean

inline_max_chars

Any of:

integer
null

integer

>= 1

content_format

Any of:

string
null

string

Allowed values: markdown text

tier

Any of:

string
null

string

Allowed values: minimalist default extended max

max_age_seconds

Any of:

integer
null

integer

no_cache

Any of:

boolean
null

boolean

metadata

Metadata

object

key

additional properties

any

Responses

200

Successful Response

application/json

InteractionResponse

object

instance_id

required

Instance Id

string

session_id

required

Session Id

string format: uuid

interaction_id

required

Interaction Id

string format: uuid

trajectory_id

Any of:

string
null

string format: uuid

parent_trajectory_id

Any of:

string
null

string format: uuid

trajectory_goal

Any of:

string
null

string

status

required

Status

string

preprocessor_runs

required

Preprocessor Runs

Array<object>

PreprocessorRunResult

object

Any of:

string
null

string format: uuid

preprocessor_name

required

Preprocessor Name

string

status

required

Status

string

batch_index

Batch Index

integer

query

Query

string

request_payload

required

Request Payload

object

key

additional properties

any

output_payload

Any of:

object
null

object

key

additional properties

any

raw_payload

Any of:

object
null

object

key

additional properties

any

error

Any of:

object
null

object

key

additional properties

any

latency_ms

Any of:

integer
null

integer

postprocessor_runs

required

Postprocessor Runs

Array<object>

PostprocessorRunResult

object

Any of:

string
null

string format: uuid

postprocessor_name

required

Postprocessor Name

string

status

required

Status

string

batch_index

Batch Index

integer

query

Query

string

preprocessor_run_ids

Preprocessor Run Ids

Array<string>

output_payload

required

Output Payload

object

key

additional properties

any

error

Any of:

object
null

object

key

additional properties

any

latency_ms

Any of:

integer
null

integer

created_at

required

Created At

string format: date-time

completed_at

Any of:

string
null

string format: date-time

normalized_schema_version

Any of:

integer
null

integer

Example

{
  "preprocessor_runs": [
    {
      "batch_index": 0,
      "query": ""
    }
  ],
  "postprocessor_runs": [
    {
      "batch_index": 0,
      "query": ""
    }
  ]
}

400

Typed request rejection. error.code is the contract and is append-only: missing_urls, invalid_url, over_url_cap, duplicate_urls, invalid_kind, invalid_session, invalid_request, unknown_provider.

application/json

ApiErrorResponse

Declared on the typed routes so the published OpenAPI shows the shape that actually arrives. Without it the schema advertises FastAPI’s HTTPValidationError — {"detail": [...]} — and a client generated from docs.telem.ai cannot deserialize the envelope, nor discover the codes it is supposed to branch on.

object

error

required

ApiErrorDetail

The error object of the typed envelope (spec 2026-08-03 §2).

object

code

required

Code

string

message

required

Message

string

param

Any of:

string
null

string

interaction_id

Any of:

string
null

string

session_id

Any of:

string
null

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "param": "example",
    "interaction_id": "example",
    "session_id": "example"
  }
}

401

Missing or invalid API key.

application/json

ApiErrorResponse

object

error

required

ApiErrorDetail

The error object of the typed envelope (spec 2026-08-03 §2).

object

code

required

Code

string

message

required

Message

string

param

Any of:

string
null

string

interaction_id

Any of:

string
null

string

session_id

Any of:

string
null

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "param": "example",
    "interaction_id": "example",
    "session_id": "example"
  }
}

403

Key may not execute fetches.

application/json

ApiErrorResponse

object

error

required

ApiErrorDetail

The error object of the typed envelope (spec 2026-08-03 §2).

object

code

required

Code

string

message

required

Message

string

param

Any of:

string
null

string

interaction_id

Any of:

string
null

string

session_id

Any of:

string
null

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "param": "example",
    "interaction_id": "example",
    "session_id": "example"
  }
}

422

Body failed schema validation. error.param points at the offending field (urls[1]).

application/json

ApiErrorResponse

object

error

required

ApiErrorDetail

The error object of the typed envelope (spec 2026-08-03 §2).

object

code

required

Code

string

message

required

Message

string

param

Any of:

string
null

string

interaction_id

Any of:

string
null

string

session_id

Any of:

string
null

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "param": "example",
    "interaction_id": "example",
    "session_id": "example"
  }
}

502

provider_unavailable: the request PINNED options.providers and every URL failed before its target was reached. Raised only for a pinned chain — a dead link, a paywall or an empty page is the target’s answer and stays a 200 result. The interaction was recorded and billed, so error.session_id and error.interaction_id identify the run. session_id is returned even when the request omitted one, since it was minted during dispatch.

application/json

ApiErrorResponse

object

error

required

ApiErrorDetail

The error object of the typed envelope (spec 2026-08-03 §2).

object

code

required

Code

string

message

required

Message

string

param

Any of:

string
null

string

interaction_id

Any of:

string
null

string

session_id

Any of:

string
null

string

Example^generated

{
  "error": {
    "code": "example",
    "message": "example",
    "param": "example",
    "interaction_id": "example",
    "session_id": "example"
  }
}

Fetch

Authorizations

Request Bodyrequired

Responses

200

Example

400

Examplegenerated

401

Examplegenerated

403

Examplegenerated

422

Examplegenerated

502

Examplegenerated

Request Body^required

Example^generated

Example^generated

Example^generated

Example^generated

Example^generated