Agent quick-brief response schema 1.2¶

The current mapper request schema is twin contract 1.7, which adds customer_tier. Version references below describe the individual quick-brief releases and do not change the current mapper contract.

Single-agent creation waits for a source-linked OpenAI brief. Bulk creation is asynchronous. Successful single-agent creation responses include the completed brief as gtm_obligations. The downstream full obligation assessment continues separately.

Create and read¶

API	Brief location
`POST /api/v2/agent-compliance/agents`	`gtm_obligations`
`GET /api/v2/agent-compliance/agents/{agent_id}` and agent lists	`gtm_obligations`
`POST /api/v2/public/funnel/submit`	`agent_results[].gtm_obligations`, paired with `agent_id`
`POST /api/v2/public/funnel/bulk` and `/batch`	202, `items[].status: "gtm_pending"`, `items[].gtm_obligations: null`; poll status
`POST /api/v2/public/funnel/edit/{case_key}`	`gtm_obligations` for the revised twin
`GET /api/v2/public/funnel/status/{case_key}`	`agents[].gtm_obligations`
`GET /api/v1/ismyagentlegal/admin/agents/{agent_id}/report`	`agent.gtm_obligations`
Admin lead lists	`agents[].gtm_obligations`

These responses include response_schema_version: "1.2". Existing fields remain. New briefs have their own schema_version: "1.3"; stored 1.0–1.2 briefs remain readable. These versions are separate from the mapper's output contract and the twin description's schema version.

The brief contains:

Field	Meaning
`agent_description`	A faithful, concise description for the one pager.
`lead_question`, `context_summary`	V3: a clearance/revenue question and available assessment scope. Historical briefs use a specific review uncertainty.
`known_facts[]`	Described facts with literal `evidence_quote` text from the submitted description. These are not independently verified deployment facts.
`findings[]`	Exactly three entries in new briefs. Weak workflow-connected leads are explicitly exploratory; historical briefs may have fewer.
`findings[].business_implication`	A possible operational or review consequence, not a claim that a deal or deployment is already blocked.
`findings[].confirmation_question`, `evidence_needed[]`	A missing fact to establish and specific evidence to review.
`findings[].capability_evidence`, `fact_basis`, `inference`	Literal capability evidence, whether the question is stated or conditional, and what remains unconfirmed.
`findings[].legal_sources[]`	Retrieved source URLs, titles, provision labels, and their relevance to the question. Retrieval does not establish applicability.
`what_could_change`	Illustrative changes that could require reassessment.
`meeting_payoff`	A bounded outcome from reviewing the questions and evidence.
`limitations[]`	Research qualifications, displayed on the one pager.
`metadata`	Generation time, model, prompt version and hash, input hash, response ID, and retrieved source URLs.

Use gtm_obligations as a preliminary review brief, not as the full obligation register. Its three findings do not establish exhaustive coverage. V3 one pagers use stored assessment-summary counts when available; they never count capped result lists.

In the admin dashboard's All Agents table, use the One pager column to open an agent's quick brief in a new tab. The link is available when one_pager_ready is true, even while the full obligation assessment is pending. An older agent with no quick brief shows Not available. The agent-name link still opens the full report when that assessment is ready.

Use an active integration key in X-API-Key:

GET /api/v2/public/funnel/agents/{agent_id}/summary.pdf
GET /api/v2/public/funnel/agents/{agent_id}/summary.png

Both formats render the same stored OpenAI response. The PNG rasterizes the PDF at 144 DPI. Long content can continue onto another PDF page; the PNG includes all pages. These calls do not generate a new model response.

The downloads require gtm_obligations, rather than a completed downstream assessment. one_pager_ready signals availability in status and report responses. ready still means the full assessment is completed. The full report.pdf remains a separate download with its existing assessment-readiness requirement.

An older twin can have gtm_obligations: null; its summary download returns 409. Generation timeouts, refusal, invalid JSON, unsupported quoted capabilities, and unretrieved citations fail creation. A successful creation does not return an empty brief. Single-agent creation/submit returns 502 for generation failure; bulk submission records the row's error and continues with the remaining rows.

Synchronous request timing¶

Allow time for web research and generation before expecting a POST response. V2 research can take up to 240 seconds per agent; base research defaults to 90 seconds. Bulk rows are processed sequentially, in addition to existing extraction work, so use small batches and a client timeout appropriate to the batch. After a connection timeout, check existing records before retrying: creation is not idempotent.

The response structure is defined by the backend-owned GTM JSON schema. OpenAI is called with Structured Outputs and web search.

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 remains 1.6. It receives only published twins, including the completed quick brief; the quick-brief content schema is 1.1 (older 1.0 briefs remain readable).

New quick briefs include agent_summary, a faithful summary capped at 160 characters, returned in the same OpenAI response as the findings. One-pager HTML, PDF, and PNG use this summary; agent_description and the original submitted description remain available in the complete response. Existing schema 1.0 briefs remain readable and use their full description until a summary is backfilled. Findings remain limited to at most three; fewer are returned when evidence cannot support three distinct review questions. The outer response schema stays 1.2 and /twin stays 1.6.

The admin one-pager has a Download 1 pager PDF button. It uses the authenticated GET /api/v2/ismyagentlegal/admin/agents/{agent_id}/summary.pdf route, which renders the same stored brief and PDF template as the integration download endpoint.

Submission metadata in generation (prompt version 1.2)¶

The OpenAI one-pager request includes the complete stored Lead.metadata object as metadata, alongside the agent name, company, description, parsed twin facts, evidence URL and current date. This includes caller-supplied nested JSON and server-recorded submission context. The same metadata is supplied on synchronous submission, asynchronous bulk processing, description revisions and explicit brief backfills. Agents without a linked lead send an empty metadata object.

Metadata guides research as unverified context. The prompt keeps contact and tracking details out of the public brief and search queries. Internal twin metadata/provenance and tenant business profiles remain excluded. This input change does not alter response schema 1.2, brief content schema 1.1 or /twin 1.6.

Prompt 1.4 requires citations to enacted legislation, regulations or court decisions on official publisher sites. An approved mirror may reproduce the legal text only when explicitly configured by the operator. Guidance, blogs, press releases and third-party explanations are excluded. Unsupported or ineligible findings are omitted with caveats, so a brief may contain fewer than three findings.

One-pagers use the launch-readiness header and closing message from the reference layout. Source-count and question-count cards are removed. The stored API content continues to include agent-specific questions and findings; response versions are unchanged.

Exploratory GTM findings (brief schema 1.2, prompt 1.5)¶

Generation accepts plausible conditional review leads at model confidence estimates as low as 25 percent. findings[].confidence_percent is an uncalibrated model estimate of usefulness for GTM review, not a measured probability that a legal obligation applies. Below 60 percent, findings are conditional and receive an explicit exploratory caveat. capability_evidence may be empty for a context-based hypothesis; it must not contain an invented quotation. Missing deployment facts are confirmation questions rather than automatic exclusions. A lead still needs a retrieved official legal-text citation or an explicitly approved mirror.

Research now uses medium search context, up to 12 tool calls per pass and 8,000 output tokens. A result with no retained findings receives one additional research pass within the shared configured timeout. If both passes retain nothing, generation reports failure instead of publishing an empty brief. Existing briefs remain intact on failed regeneration. GTM_OBLIGATIONS_MAX_TOOL_CALLS can override the per-pass search budget.

New content is version 1.2; older content versions 1.0/1.1 remain readable and may omit confidence estimates. Agent response envelopes remain 1.2; /twin remains 1.6.

Individually verified citation targets (prompt 1.6)¶

Every citation is requested as a separate search-and-open operation at section, article or chapter level. The exact tool-returned URL is preserved, including query parameters and anchors. Generation also fetches each unique citation target and rejects HTTP errors, unsupported redirects and soft-404 pages such as the U.S. Code portal's HTTP-200 "Page Not Found" response. Valid official redirects are followed and the verified destination is stored. Inaccessible citations are removed; a brief with no retained findings gets the existing second research pass rather than publishing empty content. This verifies accessibility at generation time; it cannot guarantee that publishers will keep URLs working indefinitely. The content and response schema versions remain unchanged.

Plain-text legal references (prompt 1.7)¶

GTM one-pagers and quick-brief summaries show the legal instrument and its chapter, article or section as plain text. Citation hyperlinks are removed from admin/public HTML, PDF and PNG output. Source URLs remain in stored/API content for internal provenance. Generation continues official-source research but no longer performs separate HTTP accessibility checks or drops findings because a deep link fails. This supersedes the prompt 1.6 live-link requirements. Existing stored briefs gain the presentation change without regeneration. No schema or migration change is required; low-confidence caveats, the larger research budget and automatic retries remain in place.

Exactly three findings (brief schema 1.3, prompt 1.8)¶

Every newly generated, successfully published one-pager contains exactly three findings. Both the OpenAI JSON schema and the stored-content validator enforce this count. Uncertain applicability is expressed through distinct conditional review questions, with confidence estimates as low as 25 percent and explicit caveats; confirmed legal obligations or deployment facts are not invented.

Incomplete model output, or grounding that reduces the result below three, triggers the second research pass. If the result still lacks three findings, generation fails and the existing stored brief is preserved rather than publishing an incomplete replacement. Bulk worker retries remain automatic. Older content versions 1.0–1.2 remain readable and may have fewer findings; regenerate them to produce the new three-finding version. Response envelopes stay 1.2 and /twin stays 1.6. No database migration is required.

Legal research without URL matching (prompt 1.9)¶

The prompt now researches legal instruments and provisions for plain-text references. Exact matching of each deep link against the search trace is no longer a publication gate. Official-source policy, legal-fact accuracy, conditional caveats and the exact-three requirement remain. URLs attached to legal references are internal, unverified research context; metadata.source_urls records the official URLs actually returned by the search trace. Neither link accessibility nor an exact URL spelling is required to publish the brief.

New agents and new description revisions use V2 by default. In All Agents, the One pager column shows the selected version. Regenerate base version generates and selects a basic brief. Switch to v2 restores the saved V2 brief; if V2 has not been generated yet, it is generated first. Switching is shared across admins and integration downloads, rather than being a browser preference.

The current version remains available during generation. On failure it stays selected, and the dashboard shows an error with an option to retry. An already-open one-pager must be refreshed after switching. The PDF and PNG endpoints above always return the version currently selected in the admin dashboard; no variant parameter is required.

Super-admin dashboard authentication is required for these endpoints:

POST /api/v2/ismyagentlegal/admin/agents/{agent_id}/one-pager
GET /api/v2/ismyagentlegal/admin/agents/{agent_id}/one-pager

POST body:

{"variant": "base", "regenerate": true}

Use {"variant": "v2"} to restore V2. A cached switch returns 200; generation returns 202. Poll GET until one_pager_pending is empty. Both responses include one_pager_variant (base or v2), one_pager_pending, and one_pager_error. A pending selection leaves one_pager_variant pointing to the brief still being served. Generation errors do not replace the current brief. A description change supersedes an outstanding generation for the older description.

Disable an agent¶

POST /api/v1/ismyagentlegal/admin/agents/{agent_id}/disable
X-API-Key: your-super-admin-key

No body is required. This endpoint uses a super-admin account API key, rather than a funnel integration key. It returns:

{"agent_id": "fd8c0208-6b7d-42d8-9913-10f873561699", "is_active": 0}

is_active is numeric: 1 means active (the default), and 0 means disabled. Repeated calls are safe and return 0. Disabled agents retain their descriptions, briefs, and assessment history for admin review, but are excluded from customer agent lists and new mapper work. Public PDF/PNG downloads return 404 for a disabled agent. Unknown or deleted IDs return 404; missing/invalid credentials and non-super-admin users are rejected.

Enable or disable from All Agents¶

The Status column has a separate control for every agent, including agents in multi-agent submissions. Disable sets is_active to 0; Enable restores it to 1. The row updates after the request succeeds, without resetting your search or current page. Saved briefs and the selected base/V2 version are retained. Re-enabling restores customer access, exports, and pending mapper eligibility. If initial brief generation was interrupted, it is queued again when re-enabled.

The dashboard uses the signed-in super-admin session:

POST /api/v2/ismyagentlegal/admin/agents/{agent_id}/disable
POST /api/v2/ismyagentlegal/admin/agents/{agent_id}/enable

API-key callers can also re-enable an agent with:

POST /api/v1/ismyagentlegal/admin/agents/{agent_id}/enable
X-API-Key: your-super-admin-key

No body is required. The response contains agent_id and is_active: 1. Both enable and disable are idempotent and require super-admin access.

New default briefs use gtm-one-pager-v3.md (prompt version 4.3) while preserving the existing brief JSON schema 1.3. The one pager leads with discovery, implementation and evidence, then shows one personalized review example and Assess / Implement / Review / Maintain services. All three researched findings remain in gtm_obligations.

Discovery effort represented is an illustrative approximation: assessed obligations × 2 minutes ÷ 60. It is not measured savings. Missing assessment totals display as pending; metrics become available when the full assessment arrives. Implementation counts are automated active-obligation classifications, not reviewer sign-off. The evidence count covers requested artifacts for the displayed example, not uploaded files.

Public status and admin report responses add optional one_pager, with version: "3", html and css. These contain a shared, scoped presentation rendered by the server; every submission/model-derived text value is HTML-escaped. They are not raw model-generated HTML. PDF, PNG and browser views use the same renderer. The report also provides optional mapping_generated_at and law_current_as_of. Existing gtm_obligations fields and stored content remain unchanged. Clients that do not use the presentation fields can continue reading the structured brief.

Existing base/V2 briefs retain their previous layout until regenerated. The API selection value v2 remains the default cache slot for compatibility: regenerating it now generates V3. Selecting a cached default does not upgrade its content. Use {"variant":"v2","regenerate":true} to explicitly regenerate after deployment. The base option still uses gtm-one-pager-v1.md. Failed generation leaves the previous selected brief available.

Agent quick-brief response schema 1.2¶

Create and read¶

Open the one pager from All Agents¶

Download the one pager¶