--- title: "Create a new job" method: POST path: "/v1/jobs" tags: ["Create Jobs"] --- # Create a new job `POST /v1/jobs` ## Request - Base URL: `https://gateway.app.clavata.ai:8443` - URL: `https://gateway.app.clavata.ai:8443/v1/jobs` - Auth: HTTP bearer - TypeScript: (a function with typed inputs; its response is checked against the schema) Creates a new job for content evaluation. Can be configured to wait for completion or return immediately with a job ID. Policy-first endpoint: requires a `policy_id`. ## Request body - V1CreateJobRequest - `contentData` V1ContentData[], required: The content data to be evaluated. Only one content type should be set per entry. - `contentHash` string: The hashing algorithm used will appear at the front of the hash value in this field (i.e., 'md5::hash') - `text` string: A text string to process. - `image` string, base64: A binary image file to process. - `imageUrl` string: A publicly-accessible URL that points to an image. - `metadata` object - `policyId` string, required - `threshold` number, double: The threshold to use for truthyness. If not set a default value will be used. - `expedited` boolean: If set, the job will be evaluated in expedited mode, prioritizing speed over cost. - `webhook` V1CreateJobRequestWebhook: A POST request to make when the job is complete. - `url` string, required: The URL to call when the job is complete. Must be HTTPS. - `extraHeaders` object: Any additional headers to send with the webhook request. Optional. If included, all headers will be prepended with X-Webhook- to avoid collisions. - `options` V1CreateJobRequestOptions: Options for evaluation behavior. - `options` object: Map of option keys to values. ## Response `200` A successful response. - V1CreateJobResponse - `job` V1Job: A unique evaluation job that has compared a policy to one or more pieces of content - `jobUuid` string, uuidv4 - `customerId` string, uuidv4 - `status` 'JOB_STATUS_UNSPECIFIED' | 'JOB_STATUS_PENDING' | 'JOB_STATUS_RUNNING' | 'JOB_STATUS_COMPLETED' | 'JOB_STATUS_FAILED' | 'JOB_STATUS_CANCELED' - `contentData` V1ContentData[]: Content associated with this job. In responses, includes the content hash and any metadata provided with the original request. - `contentHash` string: The hashing algorithm used will appear at the front of the hash value in this field (i.e., 'md5::hash') - `text` string: A text string to process. - `image` string, base64: A binary image file to process. - `imageUrl` string: A publicly-accessible URL that points to an image. - `metadata` object - `results` V1JobResult[] - `jobUuid` string, uuidv4 - `report` V1PolicyEvaluationReport: A report on the result of evaluating a policy against a piece of content/input. - `policyId` string, uuidv4 - `policyKey` string: This is the title of the policy as it appears in the policy editor. Do not use this to identify a policy. Use the policy_id instead. - `policyVersionId` string, uuidv4 - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `sectionEvaluationReports` PolicyEvaluationReportSectionEvaluationReport[]: Reports on the evaluation of each SECTION or LABEL block in the policy. - `name` string - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `message` string - `assertionEvaluationReports` PolicyEvaluationReportAssertionEvaluationReport[]: Each assertion in each section is evaluated - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `message` string: The text of the assertion. - `score` number, double - `exceptionEvaluationReport` PolicyEvaluationReportExceptionEvaluationReport: Outcome of an EXCEPT WHEN or UNLESS block, if present. - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `assertionEvaluationReports` PolicyEvaluationReportAssertionEvaluationReport[]: Each assertion in the exception is evaluated - … - `reviewResult` PolicyEvaluationReportReviewResult: Report on the result of a single assertion in a policy. - … - `reviewResult` PolicyEvaluationReportReviewResult: Report on the result of a single assertion in a policy. - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `score` number, double - `exceptionEvaluationReport` PolicyEvaluationReportExceptionEvaluationReport: Outcome of an EXCEPT WHEN or UNLESS block, if present. - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `assertionEvaluationReports` PolicyEvaluationReportAssertionEvaluationReport[]: Each assertion in the exception is evaluated - `result` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `message` string: The text of the assertion. - `score` number, double - `reviewResult` PolicyEvaluationReportReviewResult: Report on the result of a single assertion in a policy. - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `score` number, double - `contentHash` string: The hashing algorithm used will appear at the front of the hash value in this field (i.e., 'fnv1a128::hash-value') - `contentMetadata` object: If metadata was attached to the content when the job was created, it will be attached to the evaluation report here. - `reviewResult` PolicyEvaluationReportReviewResult: Report on the result of a single assertion in a policy. - `outcome` 'OUTCOME_UNSPECIFIED' | 'OUTCOME_FALSE' | 'OUTCOME_TRUE' | 'OUTCOME_FAILED': Evaluation outcome. TRUE, FALSE or FAILED. - `score` number, double - `threshold` number, double - `labelMatches` object: Labels that matched the content. The keys of the map are the label names, and the values are the scores for each label. This field provides a simple way to identify which labels matched the content without the need to dig into each section report. - `tokenUsage` PolicyEvaluationReportTokenUsage: Usage related to this policy evaluation. - `inputTokens` integer: The number of tokens that were sent to the service in the form of content. - `billedTokens` integer: The number of tokens that Clavata billed for this evaluation. - `multiplier` number, float: The policy complexity multiplier that was used to calculate the final billed tokens. - `labelId` string, uuidv4: The ID of the published label evaluated for label-based evaluation flows. - `labelVersionId` string, uuidv4: The ID of the published label version evaluated for label-based evaluation flows. - `created` string, date-time - `created` string, date-time - `updated` string, date-time - `completed` string, date-time - `policyId` string, uuidv4 - `policyVersionId` string, uuidv4 - `threshold` number, double - `labelId` string, uuidv4: Label ID to evaluate this job for published-label evaluation flows. - `labelVersionId` string, uuidv4: Label Version ID to evaluate this job for published-label evaluation flows. - `jobType` 'JOB_TYPE_UNSPECIFIED' | 'JOB_TYPE_STANDARD' | 'JOB_TYPE_BATCH' | 'JOB_TYPE_FREE' | 'JOB_TYPE_TEST': JobType classifies how a job was created for billing and analytics purposes. - `error` V1JobError: Details about a terminal job failure. Job status remains the authoritative success/failure signal; this message provides a stable machine-readable reason and a human-readable explanation when status is JOB_STATUS_FAILED. message is the fixed explanation for the reason, not worker error text, so it is safe to display but not useful to parse — branch on reason instead. - `reason` 'JOB_ERROR_REASON_UNSPECIFIED' | 'JOB_ERROR_REASON_JOB_FAILED' | 'JOB_ERROR_REASON_VIDEO_VALIDATION_FAILURE' | 'JOB_ERROR_REASON_VIDEO_SCENE_CEILING_EXCEEDED' | 'JOB_ERROR_REASON_HLS_REMUX_TIMEOUT_EXHAUSTED' | 'JOB_ERROR_REASON_EXECUTION_DEADLINE_EXCEEDED' | 'JOB_ERROR_REASON_ADMISSION_QUEUE_TIMEOUT' | 'JOB_ERROR_REASON_ADMISSION_FAILED' | 'JOB_ERROR_REASON_TRANSCRIPT_CHUNK_ARTIFACT_INVALID' | 'JOB_ERROR_REASON_QUOTA_EXCEEDED' | 'JOB_ERROR_REASON_CONTENT_BLOCKED' | 'JOB_ERROR_REASON_CONTENT_PRECHECK_FAILED' | 'JOB_ERROR_REASON_VIDEO_SOURCE_UNREACHABLE' | 'JOB_ERROR_REASON_CONTENT_TOO_LARGE': Why a job failed. Values are public API: existing ones are never renumbered or repurposed, but new ones are added as new failure modes appear, so clients must handle unrecognized values rather than assuming this list is complete. - JOB_ERROR_REASON_UNSPECIFIED: The reason was not recorded. Jobs that failed before this field existed report no error at all rather than this value. - JOB_ERROR_REASON_JOB_FAILED: The job failed for a reason with no more specific classification. - JOB_ERROR_REASON_VIDEO_VALIDATION_FAILURE: The submitted video could not be validated or decoded. - JOB_ERROR_REASON_VIDEO_SCENE_CEILING_EXCEEDED: The submitted video exceeds the maximum number of analyzable scenes. - JOB_ERROR_REASON_HLS_REMUX_TIMEOUT_EXHAUSTED: The submitted video stream could not be retrieved before the remux timeout. - JOB_ERROR_REASON_EXECUTION_DEADLINE_EXCEEDED: The job exceeded its execution deadline. - JOB_ERROR_REASON_ADMISSION_QUEUE_TIMEOUT: The job timed out waiting to be admitted for processing. - JOB_ERROR_REASON_ADMISSION_FAILED: The job could not be admitted for processing. - JOB_ERROR_REASON_TRANSCRIPT_CHUNK_ARTIFACT_INVALID: The audio transcript could not be processed. - JOB_ERROR_REASON_QUOTA_EXCEEDED: The customer's evaluation quota was exhausted before the job could start. - JOB_ERROR_REASON_CONTENT_BLOCKED: The submitted content was rejected by a pre-evaluation content check. - JOB_ERROR_REASON_CONTENT_PRECHECK_FAILED: The pre-evaluation content check could not be completed. - JOB_ERROR_REASON_VIDEO_SOURCE_UNREACHABLE: The submitted video URL could not be accessed (for example HTTP 403/404). - JOB_ERROR_REASON_CONTENT_TOO_LARGE: The evaluation prompt exceeds every attempted model's context window. - `message` string ## Other responses - `400`: Bad Request - `429`: Too Many Requests - `499`: Precheck Failures (Canceled) - `default`: An unexpected error response. ## Changes - **2026-10-16** `d7a854b0070f`: 1 warning - added the new `JOB_ERROR_REASON_CONTENT_TOO_LARGE` enum value to the `job/error/reason` response property for the response status `200` - **2026-09-10** `f293b5bf2c4f`: 1 info - added the optional property `job/error` to the response with the `200` status [Operation history](https://skmtc.dev/clavata/apis/clavata-public-api-v1/changes/v1/jobs/post.md) --- [API](https://skmtc.dev/clavata/apis/clavata-public-api-v1.md) - [All operations](https://skmtc.dev/clavata/apis/clavata-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/clavata/apis/clavata-public-api-v1/revisions/d7a854b0070f?raw)