Artifacts.

The problem artifacts solve

An agent produces something big — a query result, a log dump, a scraped table — and then needs three rows out of it, twice, four turns later. Pasting the whole thing back into the prompt burns the context window and the budget on every turn that follows. An artifact is that blob stored once, addressed by id, and readable by query: filter, sort, search, project, paginate. The rows come back; the other 39,997 never enter the prompt. Artifacts are scoped to the key that uploaded them. The tenant scope is always taken from your authenticated key and can never be set from the request body.

Endpoints

Endpoint	What it does
`POST` `/v1/artifacts`	Upload content and get a reference back.
`POST` `/v1/artifacts/{id}/query`	Read a slice: filter, sort, search, project, paginate.
`GET` `/v1/artifacts/{id}`	The compact descriptor — never the raw bytes.
`DELETE` `/v1/artifacts/{id}`	Delete the artifact.

Upload

POST /v1/artifacts

Field	Type	Notes
`bytes`	string · required*	The content as a string.
`content`	any	Alternative to `bytes` — a non-string value is serialized as JSON. One of the two is required.
`mimeType`	string	e.g. `text/csv`, `application/json`.
`schema`	string	A hint for the row parser when the shape isn’t inferable.
`summary`	string	A one-line human description, carried on the descriptor.
`rowCount`	number	Row count, when you already know it.
`source`	string	Where it came from. Defaults to `api:upload`.
`provenance`	object	`{ "method": "exact" \| "model-generated" \| "heuristic" \| "truncation" \| "unknown", "lossless": boolean }`.

curl https://api.layerx1.com/v1/artifacts \
  -H "authorization: Bearer $LAYERX1_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "bytes": "[{\"region\":\"eu\",\"errors\":12},{\"region\":\"us\",\"errors\":3}]",
    "mimeType": "application/json",
    "summary": "error counts by region, 2026-08-09",
    "provenance": { "method": "exact", "lossless": true }
  }'

201 Created

{
  "reference": { "artifactId": "art_...", "version": 1, "...": "..." },
  "deduped": false,
  "persisted": true
}

Identical content uploaded twice is deduplicated: the second call returns 200 with "deduped": true and the same reference. Re-uploading in a retry loop costs nothing.

Provenance defaults to { "method": "unknown", "lossless": false } — the honest default for content an agent produced. Only assert "lossless": true when the artifact really is an exact projection of its source; downstream consumers are entitled to trust it.

Query

POST /v1/artifacts/{id}/query

The body is the query. Every field is optional — an empty body reads from the top.

Field	Type	Notes
`filter`	array	Predicates, AND-combined: `{ "field", "op", "value" }`.
`sort`	array	`{ "field", "dir": "asc" \| "desc" }`, applied after filtering.
`search`	string	Case-insensitive free-text over each row’s serialized form.
`select`	string[]	Return only these keys of each row.
`offset` / `limit`	number	Pagination window.
`range`	object	Byte range, and/or `rowStart` / `rowEnd` for row ranges.
`version`	number	Pin a version. Defaults to the current head.

Operators for filter[].op: eq, ne, lt, lte, gt, gte, contains, in, exists.

Request

{
  "filter": [{ "field": "errors", "op": "gt", "value": 5 }],
  "sort": [{ "field": "errors", "dir": "desc" }],
  "select": ["region", "errors"],
  "limit": 20
}

Response

{
  "result": {
    "artifactId": "art_...",
    "version": 1,
    "rows": [{ "region": "eu", "errors": 12 }],
    "totalMatched": 1,
    "truncated": false,
    "structured": true
  }
}

totalMatched counts the rows that matched before offset/limit, and truncated tells you whether your window dropped any — together they are how a client knows to page rather than guessing from rows.length. Unstructured content (plain text, a log with no parseable rows) comes back as text instead of rows, with "structured": false. Use range to slice it.

Inspect

GET /v1/artifacts/{id}

Returns { "reference": { ... }, "descriptor": { ... } } — size, shape, summary, and provenance. Deliberately never the raw bytes: the whole point of an artifact is that the big thing stays out of the context window, so the read path is query, not get.

Delete

DELETE /v1/artifacts/{id}

Returns { "deleted": true, "artifactId": "art_..." }, or 404 if it does not exist for your key.

Errors

Same flat shape as Agent Runs — { "error": { "type", "message" } } with invalid_request (400), unauthorized (401), not_found (404), method_not_allowed (405), and not_implemented (501) when the store is not enabled on the deployment you are calling.

From the CLI

npx layerx1 artifact upload --file ./errors.json --schema json
npx layerx1 artifact query  art_123 --filter "errors:gt:5" --limit 20
npx layerx1 artifact inspect art_123
npx layerx1 artifact delete  art_123

Get started

API reference

Agent-native API

Guides

Reference

The problem artifacts solve

Endpoints

Upload

Query

Inspect

Delete

Errors

From the CLI

​The problem artifacts solve

​Endpoints

​Upload

​Query

​Inspect

​Delete

​Errors

​From the CLI

The problem artifacts solve

Endpoints

Upload

Query

Inspect

Delete

Errors

From the CLI