IsMyAgentLegal API usage¶

Download an agent's obligation summary as a one-page PDF or a shareable PNG.

Authentication¶

Send your existing ialb_… integration key in the X-API-Key header. It must be active and unrevoked. Store it server-side; do not embed it in browser code or shared links.

export IAL_API_BASE="https://YOUR_HOST/api/v2/public/funnel"
export IAL_API_KEY="YOUR_EXISTING_API_KEY"
export AGENT_ID="YOUR_AGENT_UUID"

Replace YOUR_HOST with your deployment's API host. Use the agent UUID from items[].agent_id in the /bulk or /batch response, after checking the row's error. The assessment's case key is a different identifier.

Downloads¶

Method	Path relative to the base above	Response
GET	`/agents/{agent_id}/summary.pdf`	One-page PDF (`application/pdf`)
GET	`/agents/{agent_id}/summary.png`	Summary image (`image/png`, 144 DPI)
GET	`/agents/{agent_id}/report.pdf`	Full obligation report (`application/pdf`)

The summary renders the stored OpenAI gtm_obligations brief: a consequential review question, up to three source-linked findings, business implications, and evidence to clarify the uncertainty. It includes described facts, illustrative changes, a meeting payoff, and research limitations. Its counts describe only the sources cited and review questions in the brief. See the quick-brief response contract.

Summary downloads require a stored brief (one_pager_ready), and are available before the downstream assessment completes. Older agents with no brief return 409 until their brief is generated. The full obligation report remains separate and requires full assessment completion. Long brief content continues onto another PDF page; the PNG preserves all pages without truncating the content.

The PNG shows the same brief as the PDF, rather than the interactive status website. Both include support@carveragents.ai for requesting the detailed breakdown. The PDF button opens a prefilled email containing the agent reference; PNG recipients can use the visible address and reference. Summary downloads return 409 until assessment completes.

curl --fail-with-body --silent --show-error \
  -H "X-API-Key: $IAL_API_KEY" \
  "$IAL_API_BASE/agents/$AGENT_ID/summary.pdf" -o agent-summary.pdf

curl --fail-with-body --silent --show-error \
  -H "X-API-Key: $IAL_API_KEY" \
  "$IAL_API_BASE/agents/$AGENT_ID/summary.png" -o agent-summary.png

The API returns file bytes with a download filename. Attach the downloaded PNG or PDF to your integration's reply to the requestor. The API does not email the file or create a public image URL. Recipients can open the attachment without an API key; calling the endpoint itself requires a key.

import os
from pathlib import Path
import requests

response = requests.get(
    f"{os.environ['IAL_API_BASE']}/agents/{os.environ['AGENT_ID']}/summary.png",
    headers={"X-API-Key": os.environ["IAL_API_KEY"]},
    timeout=60,
)
response.raise_for_status()
Path("agent-summary.png").write_bytes(response.content)
# Attach this file using your integration's reply/attachment API.

Errors¶

Status	Meaning / action
403	Key is missing, invalid or revoked. Check your secret.
404	Agent is unknown or deleted; malformed UUIDs also return this on summary endpoints.
409	Assessment is not complete. Wait and retry the summary download.
429	Read rate limit reached. Back off before retrying.
500	Rendering failed. Retry later; contact the operator if it persists.

API errors contain a JSON detail message. As with the existing full PDF endpoint, any active integration key can retrieve reports for any known agent UUID; access is not restricted to agents submitted with that key.

Trace evidence uploads¶

See Accepted trace schemas for supported formats, required fields, examples, and upload limits.

Trace uploads are enabled on agentlegalapi.com for testing. They are disabled on ismyagentlegal.com and all other branded sites. Uploads use the existing agent-description interview, assessment status page, and email verification flow. There is no synchronous trace evaluator for new uploads.

Complete the description questions, attach representative traces, accept the Public Services Terms, and submit. The request validates and stores the files; quick-brief generation and obligation mapping run asynchronously. The external mapper downloads the evidence and returns trace analysis alongside obligations.

Accepted formats¶

Format	File shape
Native timeline 1.0	One trace, an array, or a `traces` envelope.
OpenTelemetry	OTLP/HTTP JSON `resourceSpans[].scopeSpans[].spans[]`.
LangSmith	Individual run, array, `runs` envelope, JSONL/NDJSON; nested `child_runs` supported.
Zipkin v2	Array of spans with hexadecimal `traceId`/`id` and microsecond `timestamp`/`duration`.
Jaeger query export	`data[]` traces containing `spans[]`, `traceID`, `spanID`, `operationName`, `startTime`, and `duration`.

Files must be UTF-8 JSON, JSONL, or NDJSON. Limits are 20 files, 10 MiB per file, 50 MiB total, and 100,000 spans/events per file. Non-finite numbers, malformed records, duplicate span identities, and unsupported schema versions are rejected. OTLP protobuf, archives, and live collector ingestion are not supported. Remove secrets and personal data you do not want retained.

Native schema¶

Fetch the machine-readable JSON Schema from GET /api/v2/public/funnel/traces/schema. A minimal trace is:

{
  "schema_version": "1.0",
  "call_id": "support-run-1",
  "duration_s": 2,
  "timeline": [
    {"t": 0, "type": "message", "speaker": "caller", "text": "Can you help?"},
    {"t": 2, "type": "message", "speaker": "agent", "text": "Yes."}
  ]
}

Event times are non-negative seconds from the start, in chronological order. duration_s, if supplied, must include every event. Messages require speaker and text; tool calls require tool and object arguments; handoffs require from and to. Generic span and event records require name.

Unversioned MIVAS-style timelines are accepted as legacy 1.0 inputs, including the supplied run-trace structure. Other metadata is optional and retained; benchmark-specific fields are not required. New native producers should send schema_version: "1.0". Optional started_at must include a timezone.

Submit and retrieve evidence¶

First complete the existing /extract interview. Save one resulting agent object (name, text, twin) as agent.json, then:

curl https://agentlegalapi.com/api/v2/public/funnel/traces/submit \
  --form 'agent=<agent.json' \
  --form 'consent=true' \
  --form 'files=@traces.json'

Repeat files for additional exports. Success returns the assessment key and agent_ids; open /status/{key} to follow progress. Missing consent, incomplete agent facts, unsupported formats, invalid schemas, and exceeded limits return 400. No AI trace analysis runs inside this upload request.

GET and POST /api/v1/agent-compliance/twin use contract 1.8 and return the same top-level traces manifests for the selected agent/version. Twins without evidence return []. Each file entry contains id, name, format, size_bytes, sha256, trace_count, span_count, created_at, download_url, download_auth, normalized_download_url, and normalized_schema_version.

Fetch either relative URL on the same API origin using the same super-admin X-API-Key. Original downloads return exact bytes and X-Trace-SHA256. Normalized downloads return {"schema_version":"1.0","traces":[...]}; vendor spans become typed span events with their original records under source, including inputs, outputs, attributes, tool evidence, and identifiers when supplied. Span names are not converted into invented conversations. Normalized output is generated on demand; the checksum describes the original.

Downloads are private and unavailable for deleted twins or deleted/inactive agents. Evidence belongs to the submitted twin version and is not automatically copied to later description revisions. Counts are per file; overlapping exports can contain the same traces. Queue responses contain manifests to keep polling bounded; full evidence is retrieved separately.

Mapper trace-analysis result¶

The external mapper must fetch evidence, analyze it with the description, and include a top-level trace_analysis object in its normal POST /api/v1/agent-compliance/twin/outputs document. Existing routing, request-ID matching, claiming, retries, and obligation fields stay the same. The recommended trace-analysis shape is:

{
  "schema_version": "1.0",
  "summary": "Summary of observed behavior and coverage limitations.",
  "findings": [
    {
      "title": "Check the observed action",
      "description": "Explain the finding using supplied evidence.",
      "recommendation": "Describe the next action.",
      "trace_file_id": "uploaded-file-uuid",
      "call_id": "support-run-1",
      "evidence": [{"t": 2, "quote": "Yes."}]
    }
  ]
}

The complete object is retained with the mapping result. Verified assessment responses include it as agents[].trace_analysis; unverified responses return null. The existing assessment summary page displays its summary and findings. The external mapper implementation must be updated separately to produce these results; uploading files alone does not generate trace findings.

POST /traces/review is retired and returns 410. Previously generated reports remain readable through /traces/report/{key} with their existing access rules.

Format references: OTLP JSON, LangSmith runs, Zipkin v2 schema, and Jaeger APIs.