# Textus agent and integration guide

## Primary product: structured content with editable baseline direction

Textus supplies production material, not finished audio or a truth-verification service. One content purchase delivers complete text, metadata, provenance, and a provider-neutral editable baseline direction. Story projections retain characters, speakers, scenes, utterance boundaries, and reading guidance. Buyers may steer the performance and select downstream tools; source content remains separate from direction. Additional evidence links are useful metadata where available, not a prerequisite for entertainment.

Content contract 1.1.0 is the current product contract. Historical purchases retain their original terms and bytes.

## Discover the search capability

GET https://api.textus.dev/ returns the API index. Its `search` object declares `method: GET`, `templateFormat: RFC6570`, a `uriTemplate`, a documentation URL and metadata-only search guidance. Expand the URI template with only the criteria you need:

```text
https://api.textus.dev/api/v1/resources.json{?q,language,resourceType,author,collector,purchaseAvailable,page,limit,snapshot}
```

For example, setting only `q=friendship` and `language=en` yields `https://api.textus.dev/api/v1/resources.json?q=friendship&language=en`. Omit unused variables entirely; empty parameters are invalid. Send short content keywords, never complete prompts or personal data. For subsequent pages follow the returned canonical pagination links rather than expanding a new template.

Catalogue GET responses, including errors, carry a `Link` header with `service-meta` pointing to https://api.textus.dev/, `service-desc` to https://api.textus.dev/api/openapi.json and `service-doc` to https://textus.dev/docs/#content-discovery. Browser clients can read it through credential-free CORS. These links and the index template make search discoverable without changing the catalogue JSON, schemas, search semantics or purchase flow.

## Optional metadata search, filtering and pagination

GET https://api.textus.dev/api/v1/resources.json lists released content only. Deferred review records are excluded from listings, search, counts and pagination; runtime payment availability remains separate. Without query it returns the full `{contractVersion,data}` public catalogue. Any valid nonempty query enables pagination, with unchanged complete discovery records sorted by ID ascending. Combine filters with AND:

- `language`: exact, case-sensitive match; syntax `^[a-z]{2,3}(?:-[A-Z]{2})?$`.
- `resourceType`: exact, case-sensitive match; syntax `^[a-z][a-z_]*$`.
- `author` / `collector`: case-insensitive Unicode substring of `metadata.bibliography.authors.persons[].name` / `collectors.persons[].name`. Unknown or absent roles do not match. URL-encode names.
- `purchaseAvailable`: literal `true` or `false`, matched against the runtime offer.
- `q`: 1–200 UTF-8 bytes before normalization, at most ten whitespace-separated terms, with surrounding whitespace trimmed and repeated whitespace collapsed. Each term is a literal case-insensitive Unicode substring matched across the combined title, themes, character labels, scene titles and all bibliographic person names. Every term must match; combine with other filters using AND. Punctuation is literal, not query syntax. Control characters and queries without any letter or number are invalid. There is no stemming, translation, semantic matching, relevance ranking or paid full-text search.
- `page`: positive decimal integer, default 1, range 1–1000000.
- `limit`: positive decimal integer, default 25, range 1–100.
- `snapshot`: optional 64-character lowercase hexadecimal SHA-256 token returned by pagination, covering all filtered complete records before paging, including runtime offers.

Free metadata search (does not authorize or execute a purchase):

```bash
curl -fsS --get 'https://api.textus.dev/api/v1/resources.json' --data-urlencode 'q=friendship' --data-urlencode 'language=en' --data-urlencode 'resourceType=fable'
```

Free bibliographic filtering example:

```bash
curl -fsS 'https://api.textus.dev/api/v1/resources.json?language=de&collector=Grimm&purchaseAvailable=true&limit=25&page=1'
```

Queried responses add `pagination: {page,limit,total,snapshot,next,previous}`. Follow canonical absolute `next` and `previous` URLs, which retain `q`, all filters, page, limit and snapshot; absent links are null. Out-of-range pages return empty `data`, null `next` and a previous link to the last available page. If snapshot no longer matches, `409 catalogue_changed` means discard the previous traversal and restart at page 1 without snapshot. This prevents silently combining pages from changed catalogues; it does not reserve a purchase or freeze future availability. Unknown, duplicate, empty or malformed parameters return `400 invalid_query`; integers cannot have signs, leading zeros or fractions. The optional response envelope keeps contract 1.1.0 and does not alter paid artifacts, schemas, payment routes or recovery.

Search privacy: send brief content keywords, not the user's complete prompt, personal data, credentials, payment signatures, private keys or recovery material. Textus may retain bounded redacted search/filter text in private first-party daily demand statistics for fourteen calendar days. Redaction is heuristic and does not guarantee anonymity. The demand collector does not store raw IP addresses, raw user agents, raw URIs, request IDs, wallets, receipts or signatures. It observes only catalogue requests that reach Textus, not offline searches, private user prompts or discovery searches at other services. The complete catalogue remains available for private client-side selection; sending search intent is optional. See https://textus.dev/datenschutz/.

Responses containing `q` use `Cache-Control: private, no-store` because canonical pagination links include the search text. Full-catalogue and filter-only responses remain publicly cacheable for up to 60 seconds. Cached catalogue access and searches performed privately inside a client remain outside Textus's observations.

## Read-only MCP discovery

The public stateless Streamable HTTP MCP endpoint is `https://api.textus.dev/mcp` and accepts JSON-RPC `POST` only. It provides exactly one tool, `search_textus_resources`, over the same fixed public `GET /api/v1/resources.json` discovery contract. It accepts only public catalogue filters, returns public metadata and safe pagination inputs, and cannot buy, use a wallet, return paid text or `basisDirection`, or search Source Moments. Keep the direct API as the canonical product and purchase path; never send complete prompts, personal data, credentials, payment signatures or wallet material to either search surface. For repository-local development, `npm run mcp:start` serves the same contract at `http://127.0.0.1:3000/mcp`.

## Bibliography and purchase workflow

Current discovery records and paid artifacts both contain `metadata.bibliography`: `authors`, `collectors`, `editors` and `translators` are separate roles. Each role has `status` (`documented` or `unknown`) and `persons`, whose entries carry `name`, `sourceUrl` and `attribution` (`credited` or `traditional`). Filter the free catalogue by the required role and person before purchase; do not treat collectors as authors or infer names from unknown entries. Bibliographic attribution does not itself establish rights clearance. Current artifacts use schemaVersion `1.1`; the shared major-version-1 schemas still validate historical `1.0` deliveries, where bibliography may be absent.

1. Inspect the free catalogue query above for task fit, language, type, rights, review status, and the exact offer. Select a returned record with `offer.purchaseAvailable: true` and retain its exact `offer.url`. Do not buy if requirements, budget, or availability do not match or no suitable record is returned. Do not infer inventory beyond the live catalogue.
2. Read https://api.textus.dev/schemas/resource-discovery-1.schema.json and https://api.textus.dev/schemas/content-artifact-1.schema.json.
3. Read https://api.textus.dev/api/v1/content.terms.json and https://textus.dev/terms/. This remains a business-only offer.
4. Request the selected record's exact `offer.url` without a payment header to obtain a fresh challenge. Do not invent an ID or construct a URL from the documented route template. Use this same returned URL for the buyer-authorized retry. SKU `content-production-material-v1` has a 0.49-USDC pilot price; the fresh challenge and live offer are authoritative, never documentation alone.
5. Validate exact resource, SKU, revision, full digest, terms, network, asset, amount, pay-to address, and timeout against the fresh challenge. Retain the catalogue byte count for delivery verification; it is not a separate challenge requirement field. Use a buyer-controlled x402 v2 client. Sign only the selected resource and never reuse a signature across SKUs.
   The selected artifact's revision, digest and termsVersion are in extensions.textusProduct. Echo all challenge extensions unchanged in the payment payload. The general resource description is not an artifact fingerprint; missing or stale structured identity is rejected before verification.
6. On delivery verify exact bytes and digest and validate Content Artifact 1. The artifact contains `content` and an `editable_baseline` `basisDirection`, not a separately purchased provider adapter. Baseline guidance is not listening QA or a promise of provider acceptance.
7. For lost settled delivery, replay the identical signed request to recover receipt-bound bytes without a second settlement. Do not create another authorization when the prior outcome is ambiguous. Keep signatures and keys out of support messages.

Before purchase, evaluate https://api.textus.dev/api/v1/samples/content-production-material.json. This synthetic multi-scene dialogue demonstrates narrator and character speakers, exact utterance and non-spoken spans, bibliography, normalization, and editable casting and pace guidance. It is not a purchasable resource or a real pilot-work excerpt. Its rights explicitly permit only `evaluation`, `integration_testing` and `documentation`, not commercial production. See https://textus.dev/terms/#content-evaluation-sample. Pending editorial material is not made sellable merely by schema conversion.

When present, `basisDirection.nonSpokenSpans` identifies source stage directions or speaker labels. Its `paragraphIndex`, `startCodePoint` and `endCodePoint` locate paragraph-relative Unicode-codepoint spans to exclude from spoken output. Preserve them in the source content; they are not narrator dialogue. Baseline characters, speakers, scenes, utterances and guidance remain editable production material.

## Historical receipt recovery only

Story Reading packages and ElevenLabs plans are retired from new sales. The former story catalogue and purchase endpoints return HTTP 410 Gone for new purchases. Do not request a new payment authorization for a retired product.

For an existing settled purchase, replay the exact original request and identical payment signature. Recovery returns the original receipt-bound bytes and SKU without a second settlement. Validate against that receipt and its archived schema, not a current content offer. Historical schemas remain available for recovery validation. Retirement does not change earlier purchase rights. For an ambiguous settlement, contact support with non-secret evidence rather than creating another authorization.

## Product and support

- Website: https://textus.dev/
- Developer quickstart: https://textus.dev/docs/
- OpenAPI: https://api.textus.dev/api/openapi.json
- Terms: https://textus.dev/terms/
- Support: https://textus.dev/support/
- Imprint: https://textus.dev/impressum/
- Privacy: https://textus.dev/datenschutz/

Textus does not accept customer-text submission, conversion, enrichment, or commissions. It supplies the selected resources in the live catalogue. Never send payment signatures, private keys, seed phrases, or wallet recovery material to support.

## Delivery and HTTP behavior

Verify the exact response bytes against the selected offer's digest and byte count. Successful paid delivery includes PAYMENT-RESPONSE, X-Textus-Receipt, X-Textus-Delivery, X-Textus-Product-SKU and Content-Digest. X-Story-Receipt and X-Story-Delivery remain identical legacy aliases. Keep non-secret resource URL, receipt fingerprint, revision, digest, transaction reference and X-Request-ID for support.

- 200: public discovery/sample, or settled or recovered delivery
- 400: invalid_query on malformed discovery queries
- 402: payment required, invalid, or mismatched on an active product
- 404: no released artifact or sample; no challenge is emitted
- 409: catalogue_changed on a discovery snapshot mismatch; on paid routes, identical authorization already processing
- 410: retired catalogue or product; no new purchase
- 429: rate limit exceeded; honor Retry-After
- 503: payments unavailable or settlement requires reconciliation

Payment-related responses are private, no-store. The synthetic sample is public/cacheable. Browser clients use credential-free CORS with GET/OPTIONS. Never follow a cross-domain redirect for a signed request.