> ## Documentation Index > Fetch the complete documentation index at: https://docs.superdial.com/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve a schema > Returns the detail resource for one schema: its `name`, its `requestType`, and `resultsFields` — every field the schema can produce in `results` on `GET /v1/requests/{requestId}`. Use it to build an ingest mapping and a destination table before you run a request. Inputs are not included; use `GET /v1/schemas/{schemaId}/required-inputs` for what to send. `resultsFields` is sorted by `name`. Each `name` matches the `results` key and the top-level `missingFields` entries exactly. `callSteps[].missingFields` is a different list — it falls back to raw question text for a skipped question that carries no alias — so do not join it against this inventory. **For this schema, the inventory is a superset of any one response.** Most fields on a large schema are gated on another field's answer, so they are absent on any given request. An unanswered field is absent from `results`; it is never `null`. Every column you build from this inventory must be nullable. Map on `name`, treat every field as optional, and ignore keys you do not map. The endpoint does not report which fields are gated. **A chained request can return keys beyond this schema.** A request can open a follow-up leg: a second call against a different schema, visible as an extra `callSteps` entry. That leg's captured values merge into the same top-level `results` under the leg schema's own field names. `resultsFields` covers one schema and does not list them. Read `callSteps[].schemaId` on a completed request, then call this endpoint again for that id. **`allowedValues` is not a closed set.** `CANNOT ANSWER - ` passes through verbatim as a string on any type, including `boolean` and `multiple`, so a strict enum or boolean parse fails on it. Detect it by string prefix. It does not appear in `missingFields`: an explicit non-answer counts as answered. **Version drift.** `resultsFields` describes the schema's current latest version. A request that already ran was pinned to the version that was latest at run time. So an older request's `results` can carry keys this endpoint no longer lists, or omit keys it now lists. Read the endpoint again and diff the field list to find a change. ## OpenAPI ````yaml /openapi.json get /v1/schemas/{schemaId} openapi: 3.0.0 info: description: SuperDial REST API Reference version: 1.0.0 title: SuperDial API servers: - url: https://robodialer-service-api-9nc4t1p9.uc.gateway.dev description: Production security: [] tags: - name: Authentication description: >- SuperDial employs Bearer Authentication. Fetch a bearer token using your API Key and API Secret, then pass it as `Authorization: Bearer ` on subsequent calls. - name: Requests description: >- Endpoints for creating and reading requests (structured data extraction jobs). All non-2xx responses use the uniform `{error, message, [details]}` envelope (see the `ApiError` schema). - name: Schemas description: >- Discover the schemas provisioned for your account, the input keys each one requires, and the fields each one returns. All non-2xx responses use the uniform `{error, message, [details]}` envelope (see the `ApiError` schema). paths: /v1/schemas/{schemaId}: get: tags: - Schemas summary: Retrieve a schema description: >- Returns the detail resource for one schema: its `name`, its `requestType`, and `resultsFields` — every field the schema can produce in `results` on `GET /v1/requests/{requestId}`. Use it to build an ingest mapping and a destination table before you run a request. Inputs are not included; use `GET /v1/schemas/{schemaId}/required-inputs` for what to send. `resultsFields` is sorted by `name`. Each `name` matches the `results` key and the top-level `missingFields` entries exactly. `callSteps[].missingFields` is a different list — it falls back to raw question text for a skipped question that carries no alias — so do not join it against this inventory. **For this schema, the inventory is a superset of any one response.** Most fields on a large schema are gated on another field's answer, so they are absent on any given request. An unanswered field is absent from `results`; it is never `null`. Every column you build from this inventory must be nullable. Map on `name`, treat every field as optional, and ignore keys you do not map. The endpoint does not report which fields are gated. **A chained request can return keys beyond this schema.** A request can open a follow-up leg: a second call against a different schema, visible as an extra `callSteps` entry. That leg's captured values merge into the same top-level `results` under the leg schema's own field names. `resultsFields` covers one schema and does not list them. Read `callSteps[].schemaId` on a completed request, then call this endpoint again for that id. **`allowedValues` is not a closed set.** `CANNOT ANSWER - ` passes through verbatim as a string on any type, including `boolean` and `multiple`, so a strict enum or boolean parse fails on it. Detect it by string prefix. It does not appear in `missingFields`: an explicit non-answer counts as answered. **Version drift.** `resultsFields` describes the schema's current latest version. A request that already ran was pinned to the version that was latest at run time. So an older request's `results` can carry keys this endpoint no longer lists, or omit keys it now lists. Read the endpoint again and diff the field list to find a change. parameters: - name: schemaId in: path required: true schema: type: string description: >- The schema ID (from `GET /v1/schemas`). Must be non-blank, ≤1500 characters, contain no `/`, and must not start with `_` or `.`. responses: '200': description: >- Detail for the schema, including every field it can return in `results`. content: application/json: schema: $ref: '#/components/schemas/SchemaDetailResponse' example: schemaId: fWxzG4nqtpHsJxS5Lm3q name: Claim Status (Commercial) requestType: claim-status resultsFields: - name: checkNumber label: Check Number description: What is the check number? type: alphanumeric - name: claimReceived label: Claim Received description: Did the payer receive the claim? type: boolean - name: claimStatus label: Claim Status description: What is the status of the claim? type: multiple allowedValues: - PAID - DENIED - PENDING - name: paidAmount label: Paid Amount description: What amount was paid on the claim? type: dollar - name: paidDate label: Paid Date description: On what date was the claim paid? type: date '400': description: >- Invalid `schemaId` path parameter (empty, contains `/`, starts with `_` or `.`, or exceeds 1500 characters). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: INVALID_REQUEST message: The provided schemaId is invalid. '401': description: >- Unauthorized: enforced by the API gateway. Returned when the `Authorization: Bearer ` header is missing, malformed, or the token is invalid/expired. headers: WWW-Authenticate: description: Bearer realm and (when applicable) error code per RFC 6750. schema: type: string content: application/json: schema: $ref: '#/components/schemas/GatewayErrorResponse' examples: missingAuth: summary: No Authorization header value: code: 401 message: Jwt is missing '404': description: Schema not found, or account not found. content: application/json: schema: $ref: '#/components/schemas/ApiError' examples: schemaNotFound: summary: >- Schema not found, or has been retired and is no longer available for new requests value: error: SCHEMA_NOT_FOUND message: No schema with that ID exists for your account. accountNotFound: summary: >- The API key resolves to an account that no longer exists. Rare: wrong-API-key cases hit `INVALID_API_KEY` at `/v1/auth` first. value: error: ACCOUNT_NOT_FOUND message: >- No account is associated with this API key. Contact support if you believe this is an error. '500': description: >- Internal server error. Also returned when the schema's stored version record is unreadable or carries no fields. An empty inventory is never returned as a `200`. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: error: INTERNAL_ERROR message: >- An internal error occurred. Please try again or contact support if the problem persists. security: - bearerAuth: [] components: schemas: SchemaDetailResponse: type: object description: >- Success response from `GET /v1/schemas/{schemaId}`. New keys may be added over time; ignore ones you do not recognise. Inputs are deliberately not included — see `GET /v1/schemas/{schemaId}/required-inputs`. required: - schemaId - name - requestType - resultsFields properties: schemaId: type: string description: Echoes the path parameter. name: type: string description: >- Human-readable schema name, the same value as in `GET /v1/schemas`. Falls back to the `schemaId` when the schema sets no name. requestType: type: string description: >- The request type this schema produces (e.g. `vob`, `claim-status`), the same value as in `GET /v1/schemas`. Informational: derived from the schema, not something you supply on `POST /v1/requests`, which is keyed on `schemaId`. resultsFields: type: array items: $ref: '#/components/schemas/SchemaFieldDefinition' description: >- Every field this schema can return in `results`, sorted by `name`, describing the schema's current latest version. Never empty: a schema with no readable fields returns `500`. A superset of the keys any single request contributes from this schema. A chained request can also carry a follow-up schema's keys, which are not listed here. ApiError: type: object description: >- Uniform error envelope returned by every non-2xx response from `/v1/requests` and `/v1/schemas`. The `error` field is a stable machine-readable code; the `message` field is a human-readable description safe to surface to end users; `details` (optional) carries the structured `missingInputs` / `invalidInputs` block on the `INVALID_INPUTS` path. Unmatched paths and unsupported HTTP methods fall back to the framework's default response (typically HTML); use a documented endpoint and method to receive this envelope. required: - error - message properties: error: type: string enum: - INVALID_REQUEST - INVALID_INPUTS - PAYER_NOT_FOUND - ACCOUNT_NOT_FOUND - SCHEMA_NOT_FOUND - REQUEST_NOT_FOUND - INTERNAL_ERROR - PAYER_LOOKUP_FAILURE - PAYER_REQUIRED_INPUTS_DISABLED description: >- Machine-readable error code for the HTTP envelope. See [Creating a Request → Error handling](/guides/creating-a-request#error-handling) for what each code means, when it fires, and how to handle it. message: type: string description: >- Human-readable error description. Never contains stack traces or internal identifiers. details: type: object description: >- **Optional.** Currently set only for `INVALID_INPUTS`, where it contains `missingInputs` (array of field names) and/or `invalidInputs` (object mapping field name to reason). See the [Input Validation](/guides/input-validation) guide for the full set of rules behind these reasons. properties: missingInputs: type: array description: >- Field names that were required but absent, null, or empty/whitespace-only. items: type: string invalidInputs: type: object description: >- Maps each rejected field name to a human-readable reason (e.g. `phoneNumber is not a valid U.S. phone number`, `claimChargeAmount is scientific notation`, `memberId contains invalid characters (curly braces)`, or a member-ID structure message). additionalProperties: type: string GatewayErrorResponse: type: object description: >- Error envelope returned by the API Gateway for auth failures and routing errors. Distinct from the service's own `ApiError` envelope: gateway responses use `{code, message}` because they're produced before the request reaches the service. properties: code: type: integer description: HTTP status code, repeated in the body. example: 401 message: type: string description: Human-readable error message from the gateway. example: Jwt is missing required: - code - message SchemaFieldDefinition: type: object description: >- One field a schema can return. `name` is the key that carries this field's value in `results` on `GET /v1/requests/{requestId}`. Optional keys are omitted, never `null`. required: - name - label properties: name: type: string description: >- The `results` key for this field, and the value used in the top-level `missingFields`. Always present. label: type: string description: >- Human-readable display name. Falls back to `name` when the schema sets none. Always present. description: type: string description: >- What the field captures, usually the question the agent asks. May contain literal `{placeholder}` tokens; those are input *names*, never values. Omitted when empty. type: type: string description: >- Declared value type. Wire shapes: `boolean` → JSON `true`/`false`; `date` → ISO `yyyy-mm-dd` string; `dollar`, `number`, `percentage` → **bare-numeric string OR JSON number; accept both** (`dollar` carries no `$`); `multiple` → one of `allowedValues`; `text`, `alphanumeric`, `address`, `phoneNumber`, `faxNumber` → string. Those eleven are the full vocabulary. A schema can still declare a type outside the list, which is returned as-is, so treat an unrecognised `type` as an opaque string. A value of `CANNOT ANSWER - ` can arrive as a string on any type, including `boolean` and `multiple`. Omitted when the schema declares no type. allowedValues: type: array items: type: string description: >- The declared choices, present on `multiple` fields. **Not a closed set**: `CANNOT ANSWER - ` can arrive instead. Omitted when the schema declares no choices. securitySchemes: bearerAuth: type: http scheme: bearer description: Bearer token obtained from the /v1/auth endpoint ````