Base URL

Use the canonical production origin and versioned v1 API path for public endpoints.

https://heraldlab.si
https://heraldlab.si/api/v1

Authentication and API keys

The public application endpoint does not require an API key today. It uses request validation, a honeypot field, and server-side delivery credentials. Do not send secrets. If private APIs are added later, API keys and sandbox credentials should be issued from this portal.

Sandbox

Use validation-safe test payloads against /api/v1/apply. If delivery is not configured, the endpoint returns a typed configuration error instead of silently accepting data.

Quickstart

  1. Read /llms.txt for when agents should use Herald Labs.
  2. Read /openapi.json for typed request and response schemas.
  3. Submit applications to POST /api/v1/apply only when the user intends to apply or contact the lab about a real project.
  4. Handle non-2xx responses using the typed ErrorResponse schema.

Endpoint reference

GET /openapi.json

Machine-readable OpenAPI 3.1 description of the Herald Labs public API.

curl -sS https://heraldlab.si/openapi.json

GET /llms.txt

Agent-readable orientation, when-to-use guidance, and key public resources.

curl -sS https://heraldlab.si/llms.txt

GET /hub.json and GET /feed.xml

The latest episodes, ops logs and digests from across Herald Labs, newest first, as JSON Feed 1.1 or RSS 2.0. Each item links to its source and lists its receipts. Responses are cached for up to 15 minutes; _herald.mode is live, degraded (a source is down and its last known items are shown) or snapshot.

curl -sS https://heraldlab.si/hub.json
curl -sS https://heraldlab.si/feed.xml

POST /api/v1/apply

Submit a Herald Labs application or inquiry. This is the endpoint behind the work-with-us form. Required fields are name, email, location, track, and idea. The older /api/apply path remains a v1 compatibility alias, but agents should prefer /api/v1/apply.

curl -sS https://heraldlab.si/api/v1/apply \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Ada Example",
    "email": "ada@example.com",
    "location": "London, United Kingdom",
    "track": "Bring us a problem",
    "idea": "Agents draft our support replies but nobody reviews them. We want a human review step and a way to prove reply quality improved."
  }'

Versioning and deprecation policy

Herald Labs uses URL path versioning for public API integrations. Agents should use canonical v1 paths such as /api/v1/apply. Unversioned /api/... routes are compatibility aliases for v1, not the preferred integration surface.

Active v1 API responses include version and policy headers:

API-Version: 1
X-API-Version: 1
Deprecation: false
Link: <https://heraldlab.si/developers#versioning-policy>; rel="deprecation"; type="text/html"

If an endpoint is deprecated later, Herald Labs will signal it with Deprecation: true, a Sunset HTTP-date header, and a policy or migration Link. Public endpoint removals target at least 90 days notice unless security, abuse, or legal requirements force faster action.

Deprecation: true
Sunset: Wed, 31 Dec 2027 23:59:59 GMT
Link: <https://heraldlab.si/developers#versioning-policy>; rel="deprecation"; type="text/html"

Typed error model

All public API failures should be handled as JSON with a machine-readable code, a human-readable message, and a resolution hint.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Complete all required fields with a valid email address.",
    "hint": "Send name, email, location, track, and idea. Email must be a valid address."
  }
}