Bulk agent submission response contract 1.2

Share this contract with integrations that submit new agents in batches. The response schema is versioned through response_schema_version: "1.2" on both the batch envelope and each row. The URL remains /api/v2; that API route version is independent of this response schema version. Request fields remain unchanged; callers do not need to send a schema-version field.

Endpoint and authentication

Base URL: https://ismyagentlegal.com/api/v2/public/funnel. Submit JSON to POST /bulk with an active integration key (prefix ialb_) in X-API-Key and Content-Type: application/json.

curl --fail-with-body --silent --show-error \
  -X POST https://ismyagentlegal.com/api/v2/public/funnel/bulk \
  -H 'X-API-Key: YOUR_INTEGRATION_KEY' \
  -H 'Content-Type: application/json' \
  --data-binary @agents.json

Example agents.json (replace the example description and metadata with sourced facts):

{
  "sender_type": "pipeline",
  "agents": [{
    "agent_name": "Clinical note assistant",
    "description": "The agent drafts clinical notes from consultation audio for clinician review in California.",
    "company": "Example Clinic",
    "metadata": {
      "campaign_id": "YOUR_CAMPAIGN_ID",
      "evidence_url": "https://example.com/agent"
    }
  }]
}

Request fields

Field	Requirement
sender_type	Optional string identifying the submitting integration.
agents	Required nonempty array; default maximum 15 agents, configurable by the operator.
agents[].agent_name	Required string; an empty name receives a generated display name.
agents[].description	Required nonblank string with the sourced agent description.
agents[].company	Optional company string.
agents[].metadata	Optional object with arbitrary JSON values, stored per agent's lead. Include evidence_url when available.

Each accepted row gets its own agent, organization, and case token. Keep the returned identifiers alongside the original input and campaign metadata. Submission is not idempotent: repeating an accepted row creates another agent.

CSV callers use POST /batch, multipart fields key, file, and optional sender_type. CSV headers require agent_name and description; company is optional. CSV does not support the JSON endpoint's per-row metadata objects.

Asynchronous bulk creation (response schema 1.2)

JSON POST /api/v2/public/funnel/bulk and CSV POST /api/v2/public/funnel/batch return 202 Accepted once rows are registered. Extraction and quick-brief generation continue in the background. Single-agent creation still waits for its completed brief.

Each accepted row includes its agent_id, case key, status URL, status: "gtm_pending", one_pager_ready: false, and gtm_obligations: null. Preserve these identifiers; poll GET /api/v2/public/funnel/status/{key} instead of submitting the same agent again.

The state sequence is gtm_pending → pending → in_progress → completed. On entering pending, the stored gtm_obligations is available and one_pager_ready is true; the PDF and PNG can be downloaded before the full obligations arrive. ready continues to describe full obligations readiness.

Generation failures are retried automatically. Exhausted retries produce gtm_failed and a safe gtm_error; stop polling and ask the operator to retry the existing agent. Agents in gtm_pending or gtm_failed cannot be claimed by the downstream mapper.

Registration errors remain per-row error entries with empty identifiers. created counts registered agents, not completed briefs. A batch with no accepted rows returns 200 with its errors; invalid authentication or payloads retain their existing 4xx responses.

{
  "response_schema_version": "1.2",
  "created": 1,
  "failed": 0,
  "items": [{
    "response_schema_version": "1.2",
    "row": 1,
    "agent_name": "Clinical note assistant",
    "company": "Example Clinic",
    "agent_id": "11111111-1111-4111-8111-111111111111",
    "key": "example-case-key",
    "url": "https://ismyagentlegal.com/status/example-case-key",
    "status": "gtm_pending",
    "one_pager_ready": false,
    "gtm_obligations": null,
    "gtm_error": "",
    "error": ""
  }]
}

The mapper's /twin request contract is 1.7. It receives only published twins, including the completed quick brief; the quick-brief content schema remains 1.0.

Version history

• 1.2: JSON/CSV bulk submission becomes asynchronous. Successful registration returns 202 and exposes status, one_pager_ready, and gtm_error. The initial gtm_obligations is null; poll the status endpoint for stored content. Handle gtm_pending and gtm_failed explicitly.
• 1.1: Creation responses included the completed quick brief synchronously.

For brief fields, provenance, and downloads, see the quick-brief content guide. For the downstream queue contract, see Agent twin request contract 1.7.