# Axis' Iliad

> Analyze any codebase. Generate 152 structured AI context artifacts across 21 programs. Makes any repo immediately legible to AI coding assistants, autonomous agents, and purchasing agents.

Axis' Iliad is an API that accepts source files (or a GitHub URL) and returns structured files  -  AGENTS.md, .cursorrules, CLAUDE.md, debug playbooks, MCP configs, commerce artifacts, brand guidelines, design tokens, and more  -  each calibrated to the specific codebase.

## Quick Start

- POST /v1/accounts  -  create account, get API key (free tier available, no auth required)
- POST /v1/analyze  -  submit {github_url} or {files:[{path,content}]} → returns 152 artifacts
- GET /.well-known/axis.json  -  machine-readable capability manifest
- GET /v1/mcp/tools?q=  -  search programs by keyword (no auth required)

## MCP Integration

Connect directly via Model Context Protocol (Streamable HTTP, 2025-03-26 spec):

- Endpoint: POST /mcp
- 44 tools: analyze_repo, analyze_files, list_programs, get_snapshot, delete_snapshot, get_artifact, prepare_agentic_purchasing_preview, prepare_agentic_purchasing, closer, deploy, search_and_discover_tools, get_install_manifest, ping_payment, improve_my_agent_with_axis, discover_agentic_purchasing_needs, discover_estate_tools, get_referral_code, get_referral_credits, iliad_web_research, iliad_web_research_crawl, iliad_object_storage, iliad_vector_database, iliad_embeddings, iliad_transactional_email, iliad_llm_inference, iliad_code_sandbox, iliad_document_parsing, iliad_web_search, iliad_text_to_speech, iliad_speech_to_text, iliad_analytics, axis_validate, axis_inspect, axis_compare, axis_manifest_verify, roblox_compliance_check, iliad_hygiene, sca_exemption_decision, grade_compliance, assemble_ce3_evidence, build_ap2_mandate, score_dispute_readiness, assemble_representment, iliad_network_tokenization
- No installation required  -  connect any MCP-compatible agent to https://api.iliad.trustfabric.ai/mcp

## Estate

Sibling AXIS properties (payments, 3D generation, and more), agent-callable through their own MCP endpoints:

- GET /.well-known/axis-estate.json  -  versioned manifest of every sibling property, its MCP endpoint, and its tool prices
- discover_estate_tools  -  same data as an MCP tool call (free, no auth)

## Programs (21 total)

Free artifacts: every program ships some, with no auth and no payment (search, skills and debug are free in full)
Paid artifacts: each other program's remaining artifacts — per-run payment or a paid plan

## Agentic Commerce

For autonomous purchasing agents:

- POST /v1/prepare-for-agentic-purchasing  -  one-call hardener. Chains 10 programs, computes Purchasing Readiness Score (0-100), returns AP2/UCP/Visa compliance checklist, negotiation playbook, product schema, checkout flow, dispute handling, and self-onboarding kit.
- The Purchasing Readiness Score measures: commerce_artifacts (20pts), mcp_configs (20pts), compliance_checklist (15pts), negotiation_playbook (15pts), debug_playbook (10pts), optimization_rules (10pts), onboarding_docs (10pts).

## Authentication

- Bearer token: Authorization: Bearer <api_key>
- Obtain key: POST /v1/accounts with {email, name, tier: "free"}
- Free tier: unlimited on search/skills/debug programs, 10 snapshots/month total (pro programs need a paid tier)

## Instructions for LLM Agents

When integrating with Axis' Iliad as an LLM agent:

- Always use POST /v1/analyze as the primary entry point for codebase analysis.
- Prefer MCP transport (POST /mcp) over REST when your runtime supports Model Context Protocol.
- Do NOT embed API keys in generated artifacts or share them in client-side code.
- Every program has free artifacts that never require auth or payment. Do not prompt for auth when a call requests only free artifacts.
- For paid programs, handle 402 responses by reading the negotiation body: it includes pricing, budget headers, lite-mode alternatives, and free fallbacks.
- When receiving a 429 (quota exceeded), retry after the window resets or switch to free-only programs.
- Paid responses include a referral_token tied to the opt-in referral usage-credit program. The free get_referral_code and get_referral_credits tools report referral status.
- Use GET /.well-known/axis.json for machine-readable capability discovery, not the OpenAPI spec.
- Use POST /probe-intent with {intent: "your need"} for lightweight intent matching (free, no auth).
- Always check the adoption_hint field on returned artifacts to know where to place each file.
- If a tool behaves unexpectedly, report it: POST /v1/feedback with {message, category, email?} (free, no auth, 5/hour per network). Categories: bug, feature, question, praise, other. The response returns a ticket_id. Axis' Iliad is in beta and agent-filed reports are used directly to harden the platform — a precise report is more useful than a silent retry loop.

## MCP Response Envelope

Every successful tools/call result (free or paid, authenticated or anonymous) carries a _usage object next to content: {tier, credits_remaining, usage_credits, compensation, tool}. credits_remaining is the persistence-credit balance (spent on version-diffing, a separate pool from usage_credits). usage_credits is this month's blended-credit-pool standing: {plan_id, month_key, monthly_allowance, included_credits_used, included_credits_remaining, overage_credits_this_month}. compensation is a running lifetime total ({owed_cents, credited_cents}) for any past call that collected payment and then failed — any owed amount is auto-credited on your next call, you never claim it manually. All four are null when anonymous.

Retry a call with the same Idempotency-Key header and unchanged arguments and you get the original result back, never a second charge or run — the response carries a top-level _idempotent_replay: true instead of a fresh _usage snapshot's absence (the replayed _usage is still present, just echoing the original call's values).

A failed call never carries _usage — instead it carries _error: {code, retryable} (see MCP tool-call error categories below) and, only when that specific call had already collected an in-band cash payment before the tool threw, a one-off _compensation: {entry_id, amount_cents, status} record for exactly that incident. _compensation (singular, error-only) is a receipt for one incident; the compensation field inside _usage (success-only) is the running total across every incident.

## Error Codes

Every REST error response carries error_code alongside error (human message) and request_id. Structured JSON (same data as below, machine-readable): GET /v1/error-codes

- INVALID_JSON (400, retryable: no): The request body could not be parsed as JSON. Fix the request body so it's valid JSON, then resend.
- MISSING_FIELD (400, retryable: no): A required field was absent from the request. Add the missing required field and resend.
- INVALID_FORMAT (400, retryable: no): A field was present but malformed or out of range. Correct the field's format (see the message for specifics) and resend.
- FILE_INVALID (400, retryable: no): An uploaded file object is missing path or content. Fix the file object — every entry needs path and content — and resend.
- PATH_TRAVERSAL (400, retryable: no): A file path attempted to escape the analysis sandbox. Use a file path relative to the project root with no .. segments.
- INVALID_PROGRAM (400, retryable: no): An unknown program name was passed to an entitlement or toggle call. Use one of the documented program names.
- AUTH_REQUIRED (401, retryable: no): No Authorization header was present. Add Authorization: Bearer <api_key> and resend.
- INVALID_KEY (401, retryable: no): The supplied API key doesn't match a live account. The API key is invalid or was revoked — get a new one via POST /v1/accounts or the account's key settings.
- TIER_REQUIRED (402/403, retryable: no): The account's tier can't access this program or feature. Paid-program calls return 402 (payable in the same call); other entitlement gates return 403. Upgrade tier (see checkout_url/upgrade_url in the response) or use a free-tier program instead.
- FORBIDDEN (403, retryable: no): Authenticated, but not entitled to this specific resource. This resource isn't available to the authenticated account — verify you're using the right account or key.
- NOT_FOUND (404, retryable: no): The requested resource doesn't exist, or belongs to a different account. Check the ID or path — the resource doesn't exist, or isn't owned by this account.
- CONTEXT_PENDING (404, retryable: yes): A snapshot was found but context generation hasn't been run yet. Wait a moment and retry — the snapshot exists but its context map hasn't finished generating.
- CONFLICT (409, retryable: no): The request conflicts with existing state. Resolve the conflict described in the message (e.g. use a different email) and resend.
- CONTENT_DISCARDED (410, retryable: no): The snapshot exists, but its uploaded source content was discarded on web logout and generation can no longer read it. Re-upload the source via POST /v1/snapshots to regenerate — the account's source content was discarded when its web session logged out.
- PAYLOAD_TOO_LARGE (reserved, unused, retryable: no): Defined for future use; the current request-body-size condition uses BODY_TOO_LARGE instead. Reserved — not currently produced by any endpoint. If encountered, treat like FILE_TOO_LARGE/BODY_TOO_LARGE.
- BODY_TOO_LARGE (413, retryable: no): The raw request body exceeded the server's size ceiling. Reduce the request body below 50 MB and resend.
- FILE_TOO_LARGE (413, retryable: no): A single submitted file exceeded the tier's byte cap. Reduce the file size to fit the account's tier cap.
- FILE_COUNT_EXCEEDED (413, retryable: no): Too many files were submitted for the account's tier. Submit fewer files, or upgrade tier for a higher file-count cap.
- UNPROCESSABLE (422, retryable: no): Semantically invalid input that passed basic validation. The input was well-formed but unusable (e.g. no source files found) — fix the content and resend.
- PAYMENT_REQUIRED (402, retryable: no): A self-serve entitlement change (account creation, upgrade, credit purchase) needs payment at a non-free tier. Provide payment (see the response's checkout_url/price fields) to complete this entitlement change.
- INSUFFICIENT_CREDITS (402, retryable: depends): The account's credit balance is too low to cover this call. Top up the account's credit balance, then retry.
- SETTLEMENT_UNCONFIRMED (402, retryable: depends): Payment settlement couldn't be confirmed; a compensation entry was recorded in case the original charge succeeds asynchronously. Check whether the original charge landed before retrying — a naive retry can double-charge.
- PERSISTENCE_CREDITS_REQUIRED (402, retryable: depends): The account exhausted its persistence-operation credits. Purchase more persistence credits (version-diffing operations), then retry.
- RATE_LIMITED (429, retryable: yes): Either the per-IP anti-abuse throttle fired, or an upstream rate limit (e.g. GitHub's) was passed through. Wait for the window named in retry_after (or the Retry-After header, when present) before retrying.
- QUOTA_EXCEEDED (429, retryable: yes): The account's monthly snapshot or resource quota was reached. Wait for the monthly quota to reset, or upgrade tier for a higher quota.
- SEAT_LIMIT (429, retryable: no): The team's seat count exceeds what the tier allows. Remove a seat or upgrade tier for a higher seat cap.
- TIMEOUT (408, retryable: yes): The request exceeded the server's timeout budget. Retry the request; if it keeps timing out, reduce the payload size.
- INTERNAL_ERROR (500/502/503, retryable: depends): Catch-all server error. 503 sites are typically an unconfigured integration rather than a crash. 500/502: retry later, or contact support if it persists. 503: the integration usually isn't provisioned yet on the server — retrying won't help until that changes.
- PROCESS_FAILED (500, retryable: depends): The internal generation or processing pipeline threw. Retry once; if it fails again with the same input, the input likely triggered a real bug worth reporting.
- UPSTREAM_ERROR (502, retryable: yes): A third-party dependency failed or rejected the request. Retry after a short delay — a third-party dependency (e.g. GitHub, the payment processor) failed or rejected the call.

MCP tools/call errors instead attach a coarser _error:{code,retryable} next to the tool result, classified from the thrown error's message (not the codes above):

- auth (retryable: false): API key missing, invalid, or revoked.
- tier_limit (retryable: false): Payment or plan tier required — the tool call needs an upgrade or MPP credit, not a retry.
- quota (retryable: true): Quota exceeded, or another in-flight request already holds this Idempotency-Key — retry after the window/request clears.
- validation (retryable: false): Bad tool arguments (missing/invalid field, path, or URL).
- external (retryable: true): An upstream dependency (e.g. GitHub) failed or was unreachable.
- content_discarded (retryable: false): The snapshot exists, but its source content was discarded after the owning account's web session logged out — re-upload the source (e.g. via analyze_files/analyze_repo) to regenerate; retrying this same call won't help.
- internal (retryable: false): Uncategorized error, including genuine server bugs.

## Docs

- Full OpenAPI 3.1 spec: GET /v1/docs
- Plain-text docs: GET /v1/docs.md
- Discovery manifest: GET /.well-known/axis.json
- Security policy: GET /.well-known/security.txt
- Agent skills: GET /.well-known/skills/index.json
- MCP registry metadata: GET /v1/mcp/server.json  -  for mcp-publisher CLI and registry crawlers