{"openapi":"3.1.0","info":{"title":"Audio Decisions API","version":"1.0.0"},"paths":{"/v0/decisions/file":{"post":{"operationId":"decisions_create","summary":"Create decision","description":"Asks questions about one audio file and returns an answer to each, with the `run_id` of the model run that produced them. Each answer estimates how human raters would respond, so you choose the thresholds for acting on it.\n\nAll the questions in a request are answered in one model inference, so an answer can change when other questions are added, removed or reordered. To compare answers across recordings, send the same questions in the same order. To evaluate several files, send one request per file.","tags":["decisions"],"responses":{"200":{"description":"The answer to each question, keyed by question ID, and the `run_id` of the model run that produced the answers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DecisionsResponse"}}}},"400":{"description":"Something in the request needs correcting. `code` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"The request carried no valid credential. Check the API key you sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}}},"402":{"description":"The organization has no payment method on file, or has an unpaid invoice. An admin can update its payment method in the Hume Cloud portal.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"403":{"description":"The credential does not grant access to this API, or the organization is not permitted to use it. Contact support to request access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"413":{"description":"The request body, `request` and `file` parts together, is larger than 25,000,000 bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"415":{"description":"The request body is not `multipart/form-data`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"The request exceeds a rate limit for the account. Hume's API gateway answers it before the request reaches the service, so its body has no `code`. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}}},"500":{"description":"An unexpected error occurred on the server. Retry the request, and if it keeps failing, contact support with the `request_id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"The service is at capacity. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"requestBody":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"request":{"$ref":"#/components/schemas/DecisionsRequest"},"file":{"type":"string","format":"binary","description":"The audio file, MP3 or WAV, in a part named `file`."}},"required":["request","file"]}}}},"security":[{"ApiKey":[]}]}},"/v0/decisions/file/input_tokens":{"post":{"operationId":"decisions_inputTokens","summary":"Estimate input tokens","description":"Estimates the input tokens of a decisions request from its questions and the duration of its audio. The body takes the same `context` and `questions` as the `request` part of a `POST /v0/decisions/file` request, plus `audio_duration_ms`, the duration of the audio file in milliseconds.","tags":["decisions"],"responses":{"200":{"description":"The estimated number of input tokens for the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputTokensResponse"}}}},"400":{"description":"Something in the request needs correcting. `code` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"The request carried no valid credential. Check the API key you sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}}},"403":{"description":"The credential does not grant access to this API, or the organization is not permitted to use it. Contact support to request access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"413":{"description":"The request body is larger than 25,000,000 bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"415":{"description":"The request body is not `application/json`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"The request exceeds a rate limit for the account. Hume's API gateway answers it before the request reaches the service, so its body has no `code`. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}}},"500":{"description":"An unexpected error occurred on the server. Retry the request, and if it keeps failing, contact support with the `request_id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InputTokensRequest"}}}},"security":[{"ApiKey":[]}]}},"/v0/decisions/run":{"get":{"operationId":"runs_list","summary":"List runs","description":"Your organization's runs, newest first, one page at a time. The filters combine.\n\nA run is one model inference. A successful decisions request is recorded as a run, which can take a moment to appear in this list, and under heavy load may not be recorded. A decisions request that fails before its input reaches the model, including every request rejected with a `4xx` status, has none.","tags":["runs"],"parameters":[{"name":"page_size","in":"query","description":"How many runs to return.","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","description":"The `next_cursor` of the previous page. Pass it back unchanged, with the same filters as the request that returned it.","required":false,"schema":{"type":"string"}},{"name":"user_id","in":"query","description":"Only runs made by this user.","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","description":"Only runs with this status.","required":false,"schema":{"$ref":"#/components/schemas/RunStatus"}},{"name":"started_before","in":"query","description":"Only runs that started before this time, in RFC 3339 format.","required":false,"schema":{"type":"string","format":"date-time"}},{"name":"started_after","in":"query","description":"Only runs that started at or after this time, in RFC 3339 format. Consecutive time ranges that share a boundary neither skip a run nor return one twice.","required":false,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"One page of runs.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunsPage"}}}},"400":{"description":"A query parameter needs correcting. `code` says which.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"The request carried no valid credential. Check the API key you sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}}},"403":{"description":"The credential does not grant access to this API. Contact support to request access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"The request exceeds a rate limit for the account. Hume's API gateway answers it before the request reaches the service, so its body has no `code`. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}}},"500":{"description":"An unexpected error occurred on the server. Retry the request, and if it keeps failing, contact support with the `request_id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"The service is at capacity. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"ApiKey":[]}]}},"/v0/decisions/run/{run_id}":{"get":{"operationId":"runs_get","summary":"Get run","description":"The run's status, when it started and ended, the audio it received, and the request it evaluated. The run does not include the answers.","tags":["runs"],"parameters":[{"name":"run_id","in":"path","description":"The run's ID: the `run_id` of a decisions response. An ID that is not a UUID returns `404`, as an unknown one does.","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The run.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Run"}}}},"401":{"description":"The request carried no valid credential. Check the API key you sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}}},"403":{"description":"The credential does not grant access to this API. Contact support to request access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"404":{"description":"No run with this ID exists in your organization. A run can take a moment to appear after its decisions response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"429":{"description":"The request exceeds a rate limit for the account. Hume's API gateway answers it before the request reaches the service, so its body has no `code`. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GatewayError"}}}},"500":{"description":"An unexpected error occurred on the server. Retry the request, and if it keeps failing, contact support with the `request_id`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"503":{"description":"The service is at capacity. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}},"security":[{"ApiKey":[]}]}}},"tags":[{"name":"decisions","description":"Evaluate one audio file against one or more questions, or estimate the input tokens of a request."},{"name":"runs","description":"Look up decisions requests: their status and the request each evaluated."}],"servers":[{"url":"https://api.cloud.hume.ai","description":"Production"}],"components":{"schemas":{"NoulCriteria":{"type":"object","properties":{"true":{"type":"string","minLength":1,"maxLength":300,"description":"What counts as a yes answer."},"false":{"type":"string","minLength":1,"maxLength":300,"description":"What counts as a no answer."}},"description":"Guidance on what counts as a yes or a no answer. The model reads it along with the question.","title":"NoulCriteria"},"Criterion":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50,"description":"The option, unique within the question. The model reads it and answers are keyed by it, so make it short and self-explanatory."},"description":{"type":"string","minLength":1,"maxLength":100,"description":"More detail on when the option applies, which the model reads along with the name."}},"required":["name"],"description":"One option of a `choice` question. The model reads the option's `name` and, when it has one, its `description`. Answers are keyed by `name`.","title":"Criterion"},"Question":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["noul"],"description":"The question's primitive. Always `noul`."},"instructions":{"type":"string","minLength":1,"maxLength":500,"description":"The question, written in natural language."},"criteria":{"$ref":"#/components/schemas/NoulCriteria"}},"required":["type","instructions"],"description":"Asks a yes or no question. Optionally, say what counts as yes or no in `criteria`."},{"type":"object","properties":{"type":{"type":"string","enum":["choice"],"description":"The question's primitive. Always `choice`."},"instructions":{"type":"string","minLength":1,"maxLength":500,"description":"The question, written in natural language."},"criteria":{"type":"array","items":{"$ref":"#/components/schemas/Criterion"},"description":"The options, presented to the model in the order listed. A question with fewer than two options or more than 20, or with duplicate names, is rejected with `question_invalid`."}},"required":["type","instructions","criteria"],"description":"Asks which of two or more unordered options applies."},{"type":"object","properties":{"type":{"type":"string","enum":["score"],"description":"The question's primitive. Always `score`."},"instructions":{"type":"string","minLength":1,"maxLength":500,"description":"The question, written in natural language."},"criteria":{"type":"array","items":{"type":"string","minLength":1,"maxLength":150},"description":"The levels, ordered from lowest to highest and numbered from 0. The model reads each level's text, and the answer's `legend` returns it. A question with fewer than two levels or more than 10, or with duplicate levels, is rejected with `question_invalid`."}},"required":["type","instructions","criteria"],"description":"Asks where the audio falls on a scale of two or more ordered levels."},{"type":"object","properties":{"type":{"type":"string","enum":["span"],"description":"The question's primitive. Always `span`."},"instructions":{"type":"string","minLength":1,"maxLength":500,"description":"The question, written in natural language."}},"required":["type","instructions"],"description":"Asks when an event occurs in the audio."}],"discriminator":{"propertyName":"type"},"description":"A question. `type` names its primitive, which determines the question's options and the structure of its answer.","title":"Question"},"Questions":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Question"},"description":"The questions to answer: at most 20 `noul`, `choice` and `score` questions together, and at most 5 `span` questions. Each key is a question ID you choose, such as `agent_tone`, and can be any non-empty string of up to 256 characters. The response returns each answer under the same ID.","title":"Questions"},"DecisionsRequest":{"type":"object","properties":{"context":{"type":"string","maxLength":1000,"description":"Background information the model considers alongside the audio, such as the setting or who is speaking."},"questions":{"$ref":"#/components/schemas/Questions"}},"required":["questions"],"description":"The `request` part: the questions to answer and optional context.","title":"DecisionsRequest"},"Span":{"type":"object","properties":{"audio_start_ms":{"type":"integer","minimum":0,"description":"Where the span begins, in milliseconds from the start of the audio file."},"audio_end_ms":{"type":"integer","minimum":0,"description":"Where the span ends, in milliseconds from the start of the audio file."},"probability":{"type":"number","format":"double","minimum":0,"maximum":1,"description":"The probability that the event occurs in the span."}},"required":["audio_start_ms","audio_end_ms","probability"],"description":"A span where the described event may occur.","title":"Span"},"Answer":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["noul"],"description":"The primitive of the question answered. Always `noul`."},"noul":{"type":"number","format":"double","minimum":0,"maximum":1,"description":"The estimated share of human raters who would answer yes, from 0 to 1. A value near 0.5 means raters would split, not that the model is unsure."}},"required":["type","noul"],"description":"The answer to a `noul` question."},{"type":"object","properties":{"type":{"type":"string","enum":["choice"],"description":"The primitive of the question answered. Always `choice`."},"choice":{"type":"string","description":"The name of the option with the highest probability."},"confidence":{"type":"number","format":"double","minimum":0,"maximum":1,"description":"How much human raters would agree, from 0 when every option is equally likely to 1 when all probability is on one option."},"probabilities":{"type":"object","additionalProperties":{"type":"number","format":"double","minimum":0,"maximum":1},"description":"The probability of each option, keyed by option name. Each estimates the share of human raters who would choose the option, and together they sum to 1, within rounding."}},"required":["type","choice","confidence","probabilities"],"description":"The answer to a `choice` question."},{"type":"object","properties":{"type":{"type":"string","enum":["score"],"description":"The primitive of the question answered. Always `score`."},"score":{"type":"number","format":"double","minimum":0,"description":"The probability-weighted mean of the level indices, from 0 to the index of the highest level."},"confidence":{"type":"number","format":"double","minimum":0,"maximum":1,"description":"How much human raters would agree, from 0 when the probabilities are at least as spread out as a uniform distribution to 1 when all probability is on one level."},"probabilities":{"type":"object","additionalProperties":{"type":"number","format":"double","minimum":0,"maximum":1},"description":"The probability of each level, keyed by level index as a string. Each estimates the share of human raters who would choose the level, and together they sum to 1, within rounding."},"legend":{"type":"object","additionalProperties":{"type":"string"},"description":"The text of each level, as given in the question's `criteria`, keyed by level index like `probabilities`, so a score can be read without relying on the key order of a JSON object."}},"required":["type","score","confidence","probabilities","legend"],"description":"The answer to a `score` question."},{"type":"object","properties":{"type":{"type":"string","enum":["span"],"description":"The primitive of the question answered. Always `span`."},"spans":{"type":"array","items":{"$ref":"#/components/schemas/Span"},"description":"The spans where the described event may occur, in order of `audio_start_ms`. Overlapping candidates are merged. An empty array means the event was not found."}},"required":["type","spans"],"description":"The answer to a `span` question."}],"discriminator":{"propertyName":"type"},"description":"The answer to one question. `type` names the question's primitive and determines the answer's fields. Treat an unrecognized `type` as unknown rather than as an error.","title":"Answer"},"Answers":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/Answer"},"description":"The answer to each question, keyed by question ID.","title":"Answers"},"Received":{"type":"object","properties":{"input_tokens":{"type":"integer","minimum":0,"description":"The input tokens this request is billed. `POST /v0/decisions/file/input_tokens` estimates them before a request is sent."}},"required":["input_tokens"],"description":"What the model received for a decisions request, which is what the request is billed.","title":"Received"},"DecisionsResponse":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid","description":"Identifies this request's run. Pass it to the run endpoints to look the run up. A run can take a moment to appear, and under heavy load may not be recorded."},"answers":{"$ref":"#/components/schemas/Answers"},"received":{"$ref":"#/components/schemas/Received"}},"required":["run_id","answers","received"],"description":"The answer to each question, keyed by question ID, the `run_id` of the model run that produced the answers, and what the request is billed.","title":"DecisionsResponse"},"ErrorCode":{"type":"string","enum":["message_invalid","question_invalid","audio_decode_failed","audio_format_unsupported","audio_too_short","audio_too_long","invalid_request","payment_required","forbidden","not_found","payload_too_large","unsupported_media_type","internal_error","server_busy"],"description":"What went wrong, grouped by the HTTP status it is returned with.\n\n**`400 Bad Request`**: something in the request needs correcting.\n\n- `message_invalid`: the request body is malformed or does not match the schema outside a question, for example because a decisions request has no `request` part, or no `file` part or more than one, or an input tokens request has no `audio_duration_ms`.\n- `question_invalid`: a question is invalid, including when it does not match the schema, for example because it has duplicate option names or fewer than two options.\n- `audio_decode_failed`: the audio file could not be decoded.\n- `audio_format_unsupported`: the audio file is not MP3 or WAV.\n- `audio_too_short`: the audio is shorter than 1 second, or `audio_duration_ms` is under 1000.\n- `audio_too_long`: the audio is longer than 5 minutes, or `audio_duration_ms` is over 300000.\n- `invalid_request`: a query parameter has a value the endpoint does not accept, or `cursor` is not one the endpoint issued. List runs only.\n\n**`402 Payment Required`**\n\n- `payment_required`: the organization has no payment method on file, or has an unpaid invoice.\n\n**`403 Forbidden`**\n\n- `forbidden`: the credential does not grant access to this API, or the organization is not permitted to use it.\n\n**`404 Not Found`**\n\n- `not_found`: no run with this ID exists in your organization.\n\n**`413 Content Too Large`**\n\n- `payload_too_large`: the request body is larger than 25,000,000 bytes: for a decisions request, its `request` and `file` parts together.\n\n**`415 Unsupported Media Type`**\n\n- `unsupported_media_type`: the request body is not `multipart/form-data` for a decisions request, or not `application/json` for an input tokens request.\n\n**`500 Internal Server Error`**\n\n- `internal_error`: an unexpected error occurred on the server. Retry the request; if it keeps failing, contact support, quoting the `request_id`.\n\n**`503 Service Unavailable`**\n\n- `server_busy`: the service is at capacity. Retry after the number of seconds in the `Retry-After` header.","title":"ErrorCode"},"ErrorBody":{"type":"object","properties":{"type":{"type":"string","enum":["error"],"description":"The type of the object. Always `error`."},"code":{"$ref":"#/components/schemas/ErrorCode"},"message":{"type":"string","description":"A description of the problem for a person. Its wording may change, so switch on `code`."},"param":{"type":"string","description":"Where the error was found: a JSON Pointer into the `request` part or the input tokens body, or the name of a part or header. For a field that is missing, unknown or of the wrong type, it can name an enclosing object, such as the question, instead of the field. Omitted when the error has no narrower location than the whole request."},"request_id":{"type":"string","description":"The ID of the request that failed. Quote it when contacting support."}},"required":["type","code","message","request_id"],"description":"The body of every error response the service answers. The HTTP status says how the request failed and `code` says why.","title":"ErrorBody"},"GatewayError":{"type":"object","properties":{"message":{"type":"string","description":"A description of the problem for a person."},"request_id":{"type":"string","description":"The ID of the request. A `401` carries it only when an API key was rejected, and a `429` never does."}},"required":["message"],"description":"The body of an error that Hume's API gateway answers before the request reaches the service: a `401` for a missing or invalid credential, a `429` for a rate limit, and a `404` for a path or HTTP method the API does not serve. It carries neither `type` nor `code`.","title":"GatewayError"},"InputTokensRequest":{"type":"object","properties":{"audio_duration_ms":{"type":"integer","minimum":1000,"maximum":300000,"description":"The duration of the audio file the decisions request would send, in milliseconds. A duration under 1 second is rejected with `audio_too_short`, and one over 5 minutes with `audio_too_long`."},"context":{"type":"string","maxLength":1000,"description":"Background information the model considers alongside the audio, such as the setting or who is speaking."},"questions":{"$ref":"#/components/schemas/Questions"}},"required":["audio_duration_ms","questions"],"description":"The body of an input tokens request: the fields of the `request` part, plus the duration of the audio file.","title":"InputTokensRequest"},"InputTokensResponse":{"type":"object","properties":{"estimated_input_tokens":{"type":"integer","minimum":0,"description":"The estimated number of input tokens for the request: what `POST /v0/decisions/file` would bill it, as its response's `received.input_tokens`. The estimate counts the audio from its duration rather than the file, so it can differ slightly."}},"required":["estimated_input_tokens"],"description":"The estimated number of input tokens for a decisions request.","title":"InputTokensResponse"},"RunStatus":{"type":"string","enum":["ended","errored"],"description":"How a run ended: `ended` if it returned answers, and `errored` if it returned none because inference failed or the client closed the connection first.","title":"RunStatus"},"RunReceived":{"type":"object","properties":{"file_bytes":{"type":"integer","minimum":0,"description":"The size of the `file` part as sent, in bytes."},"input_tokens":{"type":"integer","minimum":0,"description":"The input tokens the run was billed: the decisions response's `received.input_tokens`. Absent for a run that was not billed."}},"required":["file_bytes"],"description":"The `file` part a run received, and the input tokens it was billed.","title":"RunReceived"},"RunSummary":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid","description":"The run's ID: the `run_id` of a decisions response."},"user_id":{"type":"string","description":"The ID of the Hume user who made the run."},"status":{"$ref":"#/components/schemas/RunStatus"},"started_at":{"type":"string","format":"date-time","description":"When the run started."},"ended_at":{"type":"string","format":"date-time","description":"When the run ended."},"received":{"$ref":"#/components/schemas/RunReceived"}},"required":["run_id","user_id","status","started_at","ended_at","received"],"description":"One model inference, as the list returns it.","title":"RunSummary"},"RunsPage":{"type":"object","properties":{"runs":{"type":"array","items":{"$ref":"#/components/schemas/RunSummary"},"description":"The runs, newest first."},"next_cursor":{"type":"string","description":"Absent on the last page. Pass it back as `cursor` for the next one."}},"required":["runs"],"description":"One page of runs.","title":"RunsPage"},"Run":{"type":"object","properties":{"run_id":{"type":"string","format":"uuid","description":"The run's ID: the `run_id` of a decisions response."},"user_id":{"type":"string","description":"The ID of the Hume user who made the run."},"status":{"$ref":"#/components/schemas/RunStatus"},"started_at":{"type":"string","format":"date-time","description":"When the run started."},"ended_at":{"type":"string","format":"date-time","description":"When the run ended."},"received":{"$ref":"#/components/schemas/RunReceived"},"request":{"oneOf":[{"$ref":"#/components/schemas/DecisionsRequest"},{"type":"null"}],"description":"The `request` part the run evaluated: its `context` and `questions`, as sent. `null` when the organization has zero data retention, which keeps nothing a run was sent or answered."}},"required":["run_id","user_id","status","started_at","ended_at","received","request"],"description":"One model inference in full, including the request it evaluated.","title":"Run"}},"securitySchemes":{"ApiKey":{"type":"apiKey","in":"header","name":"X-Hume-Api-Key"}}}}