Reports
Report generation is async. Create a job, then use jobs endpoints or SDK handles to wait/stream.
Schemas are generated from the API contract. Examples and guide links are maintained to stay aligned with the live API. Do not hand-edit this page.
POST /v1/reports/jobs
Create a report generation job.
Usage notes
- Raw REST expects
media.mediaId; SDK-onlysource.urlandsource.pathhelpers are not part of this HTTP request shape. webhook.urlis the recommended production completion path. Without it, complete the job with Jobs polling or streaming.idempotencyKeyis optional but strongly recommended when your client may retry the request.
Request example
curl -X POST https://api.mappa.ai/v1/reports/jobs \
-H "Mappa-Api-Key: $CONDUIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"media": { "mediaId": "media_abc123" },
"output": { "template": "sales_playbook" },
"target": { "strategy": "dominant" },
"webhook": { "url": "https://your-app.com/webhooks/conduit" },
"idempotencyKey": "report:candidate-call:v1"
}'
Response example
{
"jobId": "job_abc123",
"status": "queued",
"stage": "queued",
"estimatedWaitSec": 95
}
Common errors
422- Required fields are missing or thetargetstrategy-specific fields do not match the chosen strategy.402 insufficient_credits- Workspace credits cannot cover the requested operation.
Related guides
- Direct API workflow - Upload -> create job -> complete async work with current REST examples.
- Webhooks - Signature verification, delivery semantics, and production handler patterns.
- Error codes - HTTP statuses, billing failures, and removed-surface migration notes.
Request schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"entityLabel": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"idempotencyKey": {
"type": "string"
},
"label": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"media": {
"type": "object",
"properties": {
"mediaId": {
"type": "string"
}
},
"required": [
"mediaId"
],
"additionalProperties": false
},
"output": {
"type": "object",
"properties": {
"template": {
"type": "string",
"enum": [
"sales_playbook",
"general_report"
]
},
"templateParams": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
}
},
"required": [
"template"
],
"additionalProperties": false
},
"target": {
"type": "object",
"properties": {
"entity_id": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 256
},
{
"type": "null"
}
]
},
"hint": {
"anyOf": [
{
"type": "string",
"minLength": 1,
"maxLength": 1024
},
{
"type": "null"
}
]
},
"on_miss": {
"default": "error",
"type": "string",
"enum": [
"fallback_dominant",
"error"
]
},
"speaker_index": {
"anyOf": [
{
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
{
"type": "null"
}
]
},
"strategy": {
"type": "string",
"enum": [
"dominant",
"timerange",
"entity_id",
"magic_hint",
"speaker_index"
]
},
"timerange": {
"anyOf": [
{
"type": "object",
"properties": {
"end_seconds": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
},
"start_seconds": {
"anyOf": [
{
"type": "number",
"minimum": 0
},
{
"type": "null"
}
]
}
},
"additionalProperties": false
},
{
"type": "null"
}
]
}
},
"required": [
"on_miss",
"strategy"
],
"additionalProperties": false
},
"webhook": {
"type": "object",
"properties": {
"headers": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "string"
}
},
"url": {
"type": "string",
"format": "uri"
}
},
"required": [
"url"
],
"additionalProperties": false
}
},
"required": [
"media",
"output",
"target"
],
"additionalProperties": false
}
Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"estimatedWaitSec": {
"type": "number"
},
"jobId": {
"type": "string"
},
"stage": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"queued",
"running"
]
}
},
"required": [
"jobId",
"status"
],
"additionalProperties": false
}
GET /v1/reports/:reportId
Fetch a generated report by id.
Usage notes
- Use this endpoint when you already persisted a
reportIdfrom webhook delivery or a previous fetch. - The raw REST response exposes
markdownat the top level. SDKs normalize that content underreport.output.markdown.
Request example
curl https://api.mappa.ai/v1/reports/report_abc123 \
-H "Mappa-Api-Key: $CONDUIT_API_KEY"
Response example
{
"id": "report_abc123",
"jobId": "job_abc123",
"createdAt": "2026-03-23T12:02:30.000Z",
"media": {
"mediaId": "media_abc123",
"url": "https://storage.mappa.ai/media/media_abc123"
},
"entity": {
"id": "entity_abc123",
"label": "candidate"
},
"output": {
"template": "sales_playbook"
},
"markdown": "# Candidate report\n\n..."
}
Common errors
404 not_found- ThereportIddoes not exist in the authenticated workspace.
Related guides
- Direct API workflow - Upload -> create job -> complete async work with current REST examples.
- Error codes - HTTP statuses, billing failures, and removed-surface migration notes.
Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"entity": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"label"
],
"additionalProperties": false
},
"id": {
"type": "string"
},
"json": {
"anyOf": [
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"prompt": {
"type": "object",
"properties": {
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string",
"minLength": 1
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"labels",
"name",
"version"
],
"additionalProperties": false
},
"render": {
"type": "object",
"properties": {
"attempts": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"model": {
"type": "string",
"minLength": 1
},
"provider": {
"type": "string",
"enum": [
"openai",
"anthropic"
]
}
},
"required": [
"attempts",
"model",
"provider"
],
"additionalProperties": false
}
},
"required": [
"prompt",
"render"
],
"additionalProperties": false
},
"schemaVersion": {
"type": "number",
"const": 2
},
"sections": {
"minItems": 1,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"body": {
"type": "string",
"minLength": 1
},
"key": {
"type": "string",
"enum": [
"how_they_think",
"how_they_operate",
"what_drives_them",
"how_they_connect",
"how_they_handle_feedback",
"pressure_response",
"bottom_line",
"what_drives_a_yes",
"how_to_build_rapport_fast",
"buying_tendencies",
"how_they_handle_pushback_and_objections",
"how_they_deal_when_a_deal_gets_sticky"
]
},
"kind": {
"type": "string",
"const": "paragraph"
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"body",
"key",
"kind",
"title"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"body": {
"type": "string",
"minLength": 1
},
"key": {
"type": "string",
"const": "dominating_traits"
},
"kind": {
"type": "string",
"const": "traits"
},
"phrases": {
"type": "array",
"prefixItems": [
{
"type": "string",
"minLength": 1
},
{
"type": "string",
"minLength": 1
},
{
"type": "string",
"minLength": 1
}
]
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"body",
"key",
"kind",
"phrases",
"title"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"items": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"context": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"context",
"title"
],
"additionalProperties": false
}
},
"key": {
"type": "string",
"enum": [
"how_to_get_their_best",
"how_to_handle_the_hard_parts",
"how_to_close",
"how_to_follow_up"
]
},
"kind": {
"type": "string",
"const": "actions"
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"items",
"key",
"kind",
"title"
],
"additionalProperties": false
}
]
}
},
"summary": {
"type": "string",
"minLength": 1
},
"template": {
"type": "string",
"enum": [
"sales_playbook",
"general_report"
]
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"meta",
"schemaVersion",
"sections",
"summary",
"template",
"title"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"jobId": {
"type": "string"
},
"label": {
"type": "string"
},
"markdown": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"media": {
"type": "object",
"properties": {
"mediaId": {
"type": "string"
},
"url": {
"type": "string"
}
},
"additionalProperties": false
},
"output": {
"type": "object",
"properties": {
"template": {
"type": "string",
"enum": [
"sales_playbook",
"general_report"
]
}
},
"required": [
"template"
],
"additionalProperties": false
},
"provenance": {
"type": "object",
"properties": {
"baselineSampleIds": {
"minItems": 1,
"type": "array",
"items": {
"type": "string"
}
},
"behaviorMapId": {
"type": "string"
}
},
"required": [
"baselineSampleIds",
"behaviorMapId"
],
"additionalProperties": false
}
},
"required": [
"createdAt",
"id",
"media",
"output"
],
"additionalProperties": false
}
GET /v1/reports/by-job/:jobId
Fetch a generated report by source job id.
Usage notes
- Use this endpoint after webhook delivery or a terminal
succeededjob status when your integration only storedjobId. - The response is
nulluntil a completed report exists for that job.
Request example
curl https://api.mappa.ai/v1/reports/by-job/job_abc123 \
-H "Mappa-Api-Key: $CONDUIT_API_KEY"
Response examples
Pending job
null
Completed report
{
"id": "report_abc123",
"jobId": "job_abc123",
"createdAt": "2026-03-23T12:02:30.000Z",
"media": {
"mediaId": "media_abc123",
"url": "https://storage.mappa.ai/media/media_abc123"
},
"output": {
"template": "sales_playbook"
},
"markdown": "# Candidate report\n\n..."
}
Related guides
- Direct API workflow - Upload -> create job -> complete async work with current REST examples.
- Webhooks - Signature verification, delivery semantics, and production handler patterns.
Response schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"anyOf": [
{
"type": "object",
"properties": {
"createdAt": {
"type": "string"
},
"entity": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"id",
"label"
],
"additionalProperties": false
},
"id": {
"type": "string"
},
"json": {
"anyOf": [
{
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"prompt": {
"type": "object",
"properties": {
"labels": {
"type": "array",
"items": {
"type": "string"
}
},
"name": {
"type": "string",
"minLength": 1
},
"version": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"labels",
"name",
"version"
],
"additionalProperties": false
},
"render": {
"type": "object",
"properties": {
"attempts": {
"type": "integer",
"exclusiveMinimum": 0,
"maximum": 9007199254740991
},
"model": {
"type": "string",
"minLength": 1
},
"provider": {
"type": "string",
"enum": [
"openai",
"anthropic"
]
}
},
"required": [
"attempts",
"model",
"provider"
],
"additionalProperties": false
}
},
"required": [
"prompt",
"render"
],
"additionalProperties": false
},
"schemaVersion": {
"type": "number",
"const": 2
},
"sections": {
"minItems": 1,
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"body": {
"type": "string",
"minLength": 1
},
"key": {
"type": "string",
"enum": [
"how_they_think",
"how_they_operate",
"what_drives_them",
"how_they_connect",
"how_they_handle_feedback",
"pressure_response",
"bottom_line",
"what_drives_a_yes",
"how_to_build_rapport_fast",
"buying_tendencies",
"how_they_handle_pushback_and_objections",
"how_they_deal_when_a_deal_gets_sticky"
]
},
"kind": {
"type": "string",
"const": "paragraph"
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"body",
"key",
"kind",
"title"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"body": {
"type": "string",
"minLength": 1
},
"key": {
"type": "string",
"const": "dominating_traits"
},
"kind": {
"type": "string",
"const": "traits"
},
"phrases": {
"type": "array",
"prefixItems": [
{
"type": "string",
"minLength": 1
},
{
"type": "string",
"minLength": 1
},
{
"type": "string",
"minLength": 1
}
]
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"body",
"key",
"kind",
"phrases",
"title"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"items": {
"minItems": 1,
"type": "array",
"items": {
"type": "object",
"properties": {
"context": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"context",
"title"
],
"additionalProperties": false
}
},
"key": {
"type": "string",
"enum": [
"how_to_get_their_best",
"how_to_handle_the_hard_parts",
"how_to_close",
"how_to_follow_up"
]
},
"kind": {
"type": "string",
"const": "actions"
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"items",
"key",
"kind",
"title"
],
"additionalProperties": false
}
]
}
},
"summary": {
"type": "string",
"minLength": 1
},
"template": {
"type": "string",
"enum": [
"sales_playbook",
"general_report"
]
},
"title": {
"type": "string",
"minLength": 1
}
},
"required": [
"meta",
"schemaVersion",
"sections",
"summary",
"template",
"title"
],
"additionalProperties": false
},
{
"type": "null"
}
]
},
"jobId": {
"type": "string"
},
"label": {
"type": "string"
},
"markdown": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"media": {
"type": "object",
"properties": {
"mediaId": {
"type": "string"
},
"url": {
"type": "string"
}
},
"additionalProperties": false
},
"output": {
"type": "object",
"properties": {
"template": {
"type": "string",
"enum": [
"sales_playbook",
"general_report"
]
}
},
"required": [
"template"
],
"additionalProperties": false
},
"provenance": {
"type": "object",
"properties": {
"baselineSampleIds": {
"minItems": 1,
"type": "array",
"items": {
"type": "string"
}
},
"behaviorMapId": {
"type": "string"
}
},
"required": [
"baselineSampleIds",
"behaviorMapId"
],
"additionalProperties": false
}
},
"required": [
"createdAt",
"id",
"media",
"output"
],
"additionalProperties": false
},
{
"type": "null"
}
]
}