AI Agent Integration

WorldJen is built so an AI agent (Claude, Codex, internal tooling) can discover, authenticate, and operate it without human help. This page is the one-stop reference for that.

Discovery

• /llms.txt — index of every documentation page in plain text. Fetch https://docs.worldjen.com/llms.txt first to know what's available.
• /llms-full.txt — full concatenated documentation, ~22 KB. Use when you want one ingestion blob instead of crawling.
• This page itself is reachable at /ai-agents.md and listed in llms.txt.

Authentication

WorldJen uses long-lived API keys. Treat them like passwords — never log or echo them.

export WORLDJEN_API_KEY="wjk_..."

The key is sent as X-API-Key on every request. Keys are dashboard-only to create or revoke (the CLI surfaces a clear "go to the dashboard" error for worldjen api-keys create / revoke to keep the high-blast-radius operations out of automation).

curl -sS https://www.worldjen.com/api/v1/runs \
  -H "X-API-Key: $WORLDJEN_API_KEY"

Cross-surface contract

Every capability exists in:

1. REST API (/api/v1/*) — source of truth.
2. Python SDK (pip install worldjen) — wraps the API with typed helpers.
3. CLI (worldjen <subcommand>) — wraps the SDK; --json flag on every command for machine-readable output.

docs/sdk-cli.md shows curl, SDK, and CLI snippets side-by-side. CI enforces parity with .github/scripts/check-parity.sh so the surfaces don't drift.

Idempotency

Always send Idempotency-Key on POSTs that mutate state. The server replays the cached 2xx response for 24 hours when the same key + body are repeated, and returns 409 idempotency_mismatch if you reuse the key with a different body.

curl -sS -X POST https://www.worldjen.com/api/v1/runs \
  -H "X-API-Key: $WORLDJEN_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "demo", "dimensions": ["subject_consistency"], "model_id": "..."}'

Error codes

Branch on the code field, not on prose. Codes are stable; detail may evolve.

HTTP	code	When
400	validation_failed	Body shape is wrong
400	invalid_field	Body has a field the route doesn't accept
401	unauthorized	Missing/invalid API key
403	forbidden	Authenticated, but resource isn't yours
404	not_found	Resource missing or unknown route
409	conflict	State precondition failed
409	idempotency_mismatch	Idempotency-Key reused with different body
500	internal_error	Server bug — retry with backoff
503	upstream_unavailable	A dependency (S3, Mongo, queue) is down

Rate limits

The server does not currently enforce per-key or per-IP rate limits. Self-throttle to a few requests per second for normal use, and back off on 5xx responses. Hard limits will return in a future release; agents should be ready to honor Retry-After and standard RateLimit-* headers when they do.

Suggested agent recipe

1. GET /llms.txt to enumerate available docs.
2. GET /api/v1/dimensions and /api/v1/models to discover what to evaluate against.
3. POST /api/v1/runs with an Idempotency-Key.
4. Poll GET /api/v1/runs/{id} (or stream logs via /logs/stream) until status is completed or failed.
5. GET /api/v1/runs/{id}/csv for the scorecard, or /videos for individual results.

Same flow as worldjen.run(...) in the SDK or worldjen runs create in the CLI — they all wrap these endpoints.

Tracking and analytics

Send X-WorldJen-Source: agent (or your tool's name) so we can distinguish agentic traffic from interactive users. The SDK already sets X-WorldJen-Source: sdk. This is not used for rate limiting — it's purely for observability.