Interviews
Base URL: https://app.trymaglev.com/api/v1. All endpoint families.
POST /interviews
Section titled “POST /interviews”Start a founder or manufacturer interview.
Required scope: interviews:write.
Authentication: bearer key.
| Field | Type | Required | Details |
|---|---|---|---|
kind |
string | Yes | One of: founder, manufacturer |
201 response schema
{ "type": "object", "properties": { "interview": { "$ref": "#/components/schemas/Interview" }, "requestId": { "type": "string" } }, "required": [ "interview", "requestId" ]}Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 429 Rate limit reached; 500 Server failure. See recovery guidance.
GET /interviews/{id}
Section titled “GET /interviews/{id}”Read an interview.
Required scope: interviews:write.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
200 response schema
{ "type": "object", "properties": { "interview": { "$ref": "#/components/schemas/Interview" }, "requestId": { "type": "string" } }, "required": [ "interview", "requestId" ]}Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 404 Endpoint or record unavailable; 429 Rate limit reached; 500 Server failure. See recovery guidance.
POST /interviews/{id}/messages
Section titled “POST /interviews/{id}/messages”Answer the interviewer. Send the current version; 409 on conflict.
Required scope: interviews:write.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
| Field | Type | Required | Details |
|---|---|---|---|
message |
string | Yes | Min length 1. Max length 4000 |
version |
integer | Yes | Minimum 0 |
200 response schema
{ "type": "object", "properties": { "interview": { "$ref": "#/components/schemas/Interview" }, "missing": { "type": "array", "items": { "type": "string" } }, "engine": { "type": "string", "enum": [ "llm", "guided" ] }, "requestId": { "type": "string" } }, "required": [ "interview", "missing", "engine", "requestId" ]}Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 404 Endpoint or record unavailable; 409 Version, publication or idempotency conflict; 422 Missing facts, turn limit or quantity below MOQ; 429 Rate limit reached; 500 Server failure; 503 Dependency temporarily unavailable. See recovery guidance.
POST /interviews/{id}/publish
Section titled “POST /interviews/{id}/publish”Publish the extracted record. Manufacturer records become self reported capabilities pending Maglev review; founder records become briefs.
Confirm reviewed facts at the current version. A founder returns a brief. A manufacturer returns a capability record: 201 when created, 200 when already present. Live capabilities initially remain self-reported within the organization.
Required scope: interviews:write.
Authentication: bearer key.
| Parameter | Location | Required | Details |
|---|---|---|---|
id |
path | Yes |
| Field | Type | Required | Details |
|---|---|---|---|
confirm |
true | Yes | |
version |
integer | Yes | Minimum 0 |
200 response schema
{ "oneOf": [ { "type": "object", "properties": { "brief": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "company": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "process": { "anyOf": [ { "type": "string", "enum": [ "cnc", "pcba", "injection_molding", "sheet_metal", "3d_printing", "wire_harness", "assembly", "testing" ] }, { "type": "null" } ] }, "materials": { "type": "array", "items": { "type": "string" } }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minQuantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "unitPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "setupPriceUsd": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "leadTimeDays": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "toleranceMm": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "certifications": { "type": "array", "items": { "type": "string" } }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "quantity": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "evidence": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "quote": { "type": "string" } }, "required": [ "field", "quote" ] } }, "status": { "const": "reviewed_brief", "type": "string" } }, "required": [ "id", "company", "process", "materials", "country", "minQuantity", "unitPriceUsd", "setupPriceUsd", "leadTimeDays", "toleranceMm", "certifications", "description", "quantity", "evidence", "status" ] }, "discoverInput": { "type": "object", "properties": { "query": { "type": "string" }, "process": { "type": "string" }, "quantity": { "type": "integer" }, "material": { "type": "string" } }, "required": [ "query", "process", "quantity", "material" ] }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "brief", "discoverInput", "note", "requestId" ] }, { "type": "object", "properties": { "capability": { "$ref": "#/components/schemas/CapabilityRecord" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "capability", "note", "requestId" ] } ]}201 response schema
{ "type": "object", "properties": { "capability": { "$ref": "#/components/schemas/CapabilityRecord" }, "note": { "type": "string" }, "requestId": { "type": "string" } }, "required": [ "capability", "note", "requestId" ]}Errors: 400 Invalid input or missing idempotency header; 401 Invalid key or missing sign-in; 403 Insufficient access; 404 Endpoint or record unavailable; 409 Version, publication or idempotency conflict; 422 Missing facts, turn limit or quantity below MOQ; 429 Rate limit reached; 500 Server failure. See recovery guidance.
Response models
Section titled “Response models”Interview · Facts · Error · CapabilityRecord