canonical: https://jentic.com/apis/runtrellis.com/runtrellis

# Runtrellis Trellis

The Trellis API turns unstructured documents into structured tables an application can query. You upload assets by URL into a project, define a transform whose operations are columns that extract, classify, or generate values, and pick a model such as trellis-scale, trellis-premium, or trellis-vertix in document or table mode. Results come back per asset and row with optional references to the source text, and webhooks plus event subscriptions notify your system as processing completes.

## For AI agents

Upload documents into a Trellis project, run a transform that extracts, classifies, and generates column values, and read structured results with source references.

## Scope

Does not store documents long term, e-sign contracts, or run OCR-only scanning hardware. Use for extracting and classifying structured data from uploaded documents only.

## Capabilities

- Upload documents by URL into a project with POST `/v1/assets/upload` and choose a parse_strategy or chunk_strategy
- Create a transform whose operations define the columns to extract, classify, or generate from each asset
- Run extraction with a chosen model, trellis-scale, trellis-premium, or trellis-vertix, in document or table mode
- Fetch transform results filtered by asset_ids, row_ids, and date range, with blocking reads for fresh output
- Retrieve or generate source references that show where a row's extracted values came from
- Re-run a transform on selected assets or rows when inputs or operations change
- Register webhooks and bulk event subscriptions with actions to react when processing finishes

## Use cases

### Document extraction agent through Jentic

An agent handling incoming paperwork needs structured fields, not raw files. Through Jentic it searches for 'extract structured data from documents', receives the Trellis operations with their input schemas, and calls POST `/v1/assets/upload` with the document urls and proj_id. It then calls POST `/v1/transforms/{transform_id}/results` to read the extracted columns for those assets and hands them to the next step of the workflow.

Example prompt: Call POST `/v1/assets/upload` with urls for three invoice files, proj_id 'proj_123', and transform_id 'tr_456', then call POST `/v1/transforms/tr_456/results` with those asset_ids and return the extracted totals

### Building an extraction schema

A team turning loan files into a database defines what to pull once. POST `/v1/projects/create` makes a project with a name, and POST `/v1/transforms/create` takes proj_id and transform_params, where model is required and operations list the columns to extract, classify, or generate. GET `/v1/transforms/{transform_id}/autoschema` suggests a schema from the uploaded assets as a starting point.

Example prompt: Call POST `/v1/projects/create` with name 'Loan files', then POST `/v1/transforms/create` with that proj_id and transform_params model 'trellis-premium' and mode 'document', and review GET `/v1/transforms/{transform_id}/autoschema`

### Traceable answers with source references

Reviewers want to see where each extracted value came from before approving it. POST `/v1/transforms/{transform_id}/rows/{row_id}/references` retrieves or generates references for a row, linking values back to the source text. PATCH `/v1/transforms/{transform_id}` refreshes a transform for chosen asset_ids or row_ids, with include_reference to regenerate references during the re-run.

Example prompt: Call POST `/v1/transforms/tr_456/rows/row_789/references` and list each extracted value with its referenced source passage

### Event-driven processing

Pipelines that should not poll can subscribe to Trellis events. POST `/v1/webhook` registers a url with an auth_key that Trellis sends with each delivery, GET `/v1/webhook` lists registered webhooks, and POST `/v1/events/subscriptions/actions/bulk` creates event subscriptions with actions from an events_with_actions list.

Example prompt: Call POST `/v1/webhook` with url 'https://example.com/trellis-hook' and an auth_key, then confirm it with GET `/v1/webhook`

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/v1/assets/upload` | Upload assets by URL |
| POST | `/v1/transforms/create` | Create a transform |
| POST | `/v1/transforms/{transform_id}/results` | Get transform results |
| PATCH | `/v1/transforms/{transform_id}` | Refresh a transform |
| POST | `/v1/transforms/{transform_id}/rows/{row_id}/references` | Retrieve or generate references on a row |
| POST | `/v1/projects/create` | Create a project |
| POST | `/v1/webhook` | Create a webhook |

## Key resources

- **Projects** — Containers for assets and transforms, with create, list, and delete
- **Assets** — Uploaded documents with presigned upload URLs, URL-based upload, listing by status, and deletion
- **Transforms** — Extraction definitions with operations and model, plus results, rows, refresh, autoschema, and references
- **Workflows** — Named workflows per project, listed and created by project_id
- **Webhooks and events** — Webhook registration with an auth_key, and bulk event subscriptions with actions

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 61 / 100
- **Maturity:** AI-Aware
- **Dimensions:**
  - Foundational Compliance: 47 / 100
  - Developer Experience & Jentic Compatibility: 71 / 100
  - AI-Readiness & Agent Experience: 53 / 100
  - Agent Usability: 94 / 100
  - Security: 50 / 100
  - AI Discoverability: 65 / 100
- **View full report:** https://jentic.com/apis/runtrellis.com/runtrellis/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring Trellis by hand means putting your key in the Authorization header, pinning an API-Version header, and sequencing project, transform, upload, and results calls with the right ids. Through Jentic you install once, import Trellis from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** Trellis puts the transform id in the URL path (`/v1/transforms/{transform_id}/...`), so a rule can pin your agent to one transform's results, rows, and references. You choose the operations it may call, so destructive ones like deleting a project or an asset are not included unless you add them.
- **Credential handling:** Your Trellis API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'extract structured data from documents' or 'get transform results', and Jentic returns the matching Trellis operation with its input schema so the agent calls the right endpoint without reading the docs.

## Related APIs

- **Sensible API** — Document extraction with configurable layouts and LLM queries
- **Rossum Document Processing API** — Transactional document capture with validation queues
- **Mindee OCR API** — OCR and prebuilt document parsing models
- **Box API** — Cloud content storage and file sharing

## FAQ

### What authentication does the Trellis API use?

The Trellis API declares an apiKey scheme named APIKeyHeader in its OpenAPI spec, which sends your key in the `Authorization` header, and applies it globally. Operations also accept an optional `API-Version` header. Through Jentic the key is held by your own Jentic One instance and attached at call time.

### Can I choose which model Trellis uses for extraction?

Yes. When you call POST `/v1/transforms/create`, transform_params requires a model, which the spec says must be one of trellis-scale, trellis-premium, or trellis-vertix, and a mode of document or table. The operations list defines the columns, and at least one parse column of the assets type is required.

### What are the rate limits for the Trellis API?

The OpenAPI spec does not specify rate limits. Check the Trellis site at https://runtrellis.com for current limits before uploading large batches of assets.

### How do I extract data from documents through Jentic?

Search Jentic for 'extract structured data from documents', load POST `/v1/assets/upload`, and execute it with the document urls, your proj_id, and transform_id. Then call POST `/v1/transforms/{transform_id}/results` with the asset_ids to read the extracted rows. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Is there a Trellis MCP server?

You don't need an MCP server to give your agent Trellis. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent finds the upload, transform, and results operations it needs on demand, without loading extra tool definitions into its context.

### Can I limit what my agent is allowed to do with the Trellis API?

Yes. For an extraction worker, write a rule that allows POST `/v1/assets/upload` and POST `/v1/transforms/{transform_id}/results` under one transform id. The agent can submit documents and read that transform's output but cannot create transforms, delete projects, or register webhooks, and each call it makes is logged.
