Crevio Jobs API

openapi: 3.2.0
info:
  title: Crevio API V1 Jobs API
  version: 1.0.0
  description: 'API for the Crevio creator platform — a multi-tenant SaaS for digital product sales.

    Uses snake_case keys following Stripe conventions. All resource IDs are string IDs (e.g., "prod_abc123").


    Authentication is a bearer token: `Authorization: Bearer $CREVIO_API_KEY`.

    List endpoints are cursor-paginated with `limit` and `starting_after`.

    Writes accept an `Idempotency-Key` header and are safe to retry.


    Every response carries IETF RateLimit headers (`RateLimit`, `RateLimit-Policy`) so a client can

    self-throttle, and `Retry-After` on a 429. The quota is 600 requests per minute per credential.


    The API is versioned in the URL path (`/v1`). Nothing is removed without in-band warning: a

    deprecated operation is marked `"deprecated": true` here and serves `Deprecation` (RFC 9745),

    `Sunset` (RFC 8594) and `Link; rel="deprecation"` headers for at least six months before it

    stops answering. See https://crevio.co/docs/developer/guides/versioning.'
  contact:
    email: support@crevio.co
    name: Crevio Support
    url: https://crevio.co/docs
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://crevio.co/legal/terms-of-service
servers:
- url: https://api.crevio.co/v1
  description: Production
security:
- ApiKey: []
tags:
- name: Jobs
  description: Long-running asynchronous jobs
paths:
  /jobs:
    get:
      summary: List jobs
      description: Returns a list of generation jobs for the current account, most recent first. Filter by status and type.
      operationId: listJobs
      x-crevio-sdk-method: list
      tags:
      - Jobs
      security:
      - ApiKey: []
      parameters:
      - name: status
        in: query
        description: Filter by job status
        schema:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
      - name: type
        in: query
        description: Filter by job type
        schema:
          type: string
          enum:
          - image_generation
          - image_edit
          - image_upscale
          - video_generation
          - audio_generation
          - music_generation
      - name: starting_after
        in: query
        description: Cursor for pagination — the ID of the last item in the previous page
        schema:
          type: string
      - name: limit
        in: query
        description: Items per page
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
      responses:
        '200':
          description: List of jobs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListResponse_ProviderJob'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.jobs.list({});\n\n  console.log(result);\n}\n\nrun();"
  /jobs/{id}:
    get:
      summary: Get job
      description: Returns a specific generation job, including its status, progress, and result.
      operationId: getJob
      x-crevio-sdk-method: get
      tags:
      - Jobs
      security:
      - ApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        description: The resource ID (e.g., "prod_abc123") or slug (e.g., "my-product")
        schema:
          type: string
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProviderJob'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.jobs.get({\n    id: \"<id>\",\n  });\n\n  console.log(result);\n}\n\nrun();"
    delete:
      summary: Cancel job
      description: Cancels a queued or processing job. No credits are charged for cancelled jobs, so credits_refunded is always 0. Returns 409 if the job is already in a terminal state.
      operationId: cancelJob
      x-crevio-sdk-method: cancel
      tags:
      - Jobs
      security:
      - ApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        description: The resource ID (e.g., "prod_abc123") or slug (e.g., "my-product")
        schema:
          type: string
      responses:
        '200':
          description: Job cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobCancelResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Job is not cancellable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.jobs.cancel({\n    id: \"<id>\",\n  });\n\n  console.log(result);\n}\n\nrun();"
  /jobs/{id}/stream:
    get:
      summary: Stream a job
      description: Follow an async generation job (images, video, audio, web) over Server-Sent Events instead of polling GET /jobs/{id}. Closes when the job reaches `completed`, `failed`, or `cancelled`.
      operationId: streamJob
      x-crevio-sdk-method: stream
      tags:
      - Jobs
      security:
      - ApiKey: []
      parameters:
      - name: id
        in: path
        required: true
        description: Job id (job_...)
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/EventStream'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-crevio-approval: allow
      x-codeSamples:
      - lang: typescript
        label: Typescript (SDK)
        source: "import { Crevio } from \"@crevio/sdk\";\n\nconst crevio = new Crevio({\n  apiKey: process.env[\"CREVIO_API_KEY\"] ?? \"\",\n});\n\nasync function run() {\n  const result = await crevio.jobs.stream({\n    id: \"<id>\",\n  });\n\n  console.log(result);\n}\n\nrun();"
webhooks:
  job.completed:
    post:
      tags:
      - Jobs
      summary: Job completed
      description: Triggered when a generation job completes successfully
      operationId: webhookJobCompleted
      security: []
      parameters:
      - name: webhook-id
        in: header
        required: true
        description: The event's id, identical on every retry and equal to `id` in the body. Store it to ignore a delivery you have already handled.
        schema:
          type: string
      - name: webhook-timestamp
        in: header
        required: true
        description: Unix seconds when this attempt was sent. Reject anything older than five minutes.
        schema:
          type: string
      - name: webhook-signature
        in: header
        required: true
        description: '`v1,<signature>`, per the Standard Webhooks specification: the base64 HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<raw request body>`, keyed with the bytes your `whsec_` secret encodes. Verify it with a Standard Webhooks library before processing the event.'
        schema:
          type: string
      requestBody:
        description: Event payload Crevio POSTs to your endpoint.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for this webhook event
                  example: whev_abc123
                object:
                  type: string
                  enum:
                  - event
                  example: event
                type:
                  type: string
                  enum:
                  - job.completed
                  description: The event type
                  example: job.completed
                livemode:
                  type: boolean
                  description: '`false` when a test purchase or a test event from the dashboard caused this event, `true` otherwise'
                  example: true
                created_at:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp of when the event was created
                  example: '2025-01-15T10:30:00Z'
                api_version:
                  type: string
                  description: API version used to generate the payload
                  example: v1
                data:
                  type: object
                  description: '`object` is the resource exactly as its API endpoint returns it.'
                  properties:
                    object:
                      $ref: '#/components/schemas/ProviderJob'
                  required:
                  - object
              required:
              - id
              - object
              - type
              - livemode
              - created_at
              - api_version
              - data
      responses:
        '200':
          description: Return any 2xx status within 5 seconds to acknowledge receipt.
  job.failed:
    post:
      tags:
      - Jobs
      summary: Job failed
      description: Triggered when a generation job fails
      operationId: webhookJobFailed
      security: []
      parameters:
      - name: webhook-id
        in: header
        required: true
        description: The event's id, identical on every retry and equal to `id` in the body. Store it to ignore a delivery you have already handled.
        schema:
          type: string
      - name: webhook-timestamp
        in: header
        required: true
        description: Unix seconds when this attempt was sent. Reject anything older than five minutes.
        schema:
          type: string
      - name: webhook-signature
        in: header
        required: true
        description: '`v1,<signature>`, per the Standard Webhooks specification: the base64 HMAC-SHA256 of `<webhook-id>.<webhook-timestamp>.<raw request body>`, keyed with the bytes your `whsec_` secret encodes. Verify it with a Standard Webhooks library before processing the event.'
        schema:
          type: string
      requestBody:
        description: Event payload Crevio POSTs to your endpoint.
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: string
                  description: Unique identifier for this webhook event
                  example: whev_abc123
                object:
                  type: string
                  enum:
                  - event
                  example: event
                type:
                  type: string
                  enum:
                  - job.failed
                  description: The event type
                  example: job.failed
                livemode:
                  type: boolean
                  description: '`false` when a test purchase or a test event from the dashboard caused this event, `true` otherwise'
                  example: true
                created_at:
                  type: string
                  format: date-time
                  description: ISO 8601 timestamp of when the event was created
                  example: '2025-01-15T10:30:00Z'
                api_version:
                  type: string
                  description: API version used to generate the payload
                  example: v1
                data:
                  type: object
                  description: '`object` is the resource exactly as its API endpoint returns it.'
                  properties:
                    object:
                      $ref: '#/components/schemas/ProviderJob'
                  required:
                  - object
              required:
              - id
              - object
              - type
              - livemode
              - created_at
              - api_version
              - data
      responses:
        '200':
          description: Return any 2xx status within 5 seconds to acknowledge receipt.
components:
  responses:
    TooManyRequests:
      description: 'Rate limit exceeded — 600 requests per minute per owner on the free tier: every API key and OAuth token one person holds on an account shares one budget, and the account''s team keys share another. Retry after the number of seconds in `Retry-After`.'
      headers:
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: rate_limit_exceeded
              message: Too many requests. Please retry later.
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: forbidden
              message: You do not have permission to perform this action
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: api_error
              code: internal_error
              message: An unexpected error occurred
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    EventStream:
      description: SSE stream of the resource.
      content:
        text/event-stream:
          schema:
            type: string
            description: 'SSE stream. Events: `snapshot` (full object on connect), `update` (full object on each change), `done` (terminal state reached, stream closes), `close` (stream ended without a terminal state — reconnect to continue). `: keep-alive` comments are sent every 15s. State lives server-side, so reconnecting resumes losslessly with a fresh snapshot.'
    BadRequest:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: bad_request
              message: The request was malformed or contained invalid parameters
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: resource_missing
              message: The requested resource was not found
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              type: invalid_request_error
              code: authentication_required
              message: You did not provide an API key.
      headers:
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimitPolicy'
        Request-Id:
          $ref: '#/components/headers/RequestId'
        Deprecation:
          $ref: '#/components/headers/Deprecation'
        Sunset:
          $ref: '#/components/headers/Sunset'
        Link:
          $ref: '#/components/headers/DeprecationLink'
  schemas:
    JobCancelResponse:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - job
        status:
          type: string
          enum:
          - cancelled
        credits_refunded:
          type: integer
      required:
      - id
      - object
      - status
      - credits_refunded
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              enum:
              - api_error
              - invalid_request_error
              - validation_error
            code:
              type: string
            message:
              type: string
            param:
              type: string
            errors:
              type: object
            doc_url:
              type: string
          required:
          - type
          - message
      required:
      - error
    ProviderJob:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
        type:
          type: string
        status:
          type: string
          enum:
          - queued
          - processing
          - completed
          - failed
          - cancelled
        model:
          type: string
        progress:
          type: integer
        input:
          type: object
        result:
          type:
          - object
          - 'null'
        error:
          type:
          - string
          - 'null'
        error_code:
          type:
          - string
          - 'null'
        credits_used:
          type:
          - integer
          - 'null'
        provider_request_id:
          type:
          - string
          - 'null'
        created_at:
          type: string
          format: date-time
        started_at:
          type:
          - string
          - 'null'
          format: date-time
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
      required:
      - id
      - object
      - type
      - status
      - model
      - progress
      - input
      - result
      - error
      - error_code
      - credits_used
      - provider_request_id
      - created_at
      - started_at
      - completed_at
    ListResponse_ProviderJob:
      type: object
      properties:
        object:
          type: string
          enum:
          - list
        data:
          type: array
          items:
            $ref: '#/components/schemas/ProviderJob'
        has_more:
          type: boolean
        url:
          type: string
      required:
      - object
      - data
      - has_more
      - url
  headers:
    RetryAfter:
      description: Seconds to wait before retrying.
      schema:
        type: integer
        examples:
        - 11
    Sunset:
      description: Present only on a deprecated operation. HTTP-date (RFC 8594) after which the operation stops responding. Always at least six months after `Deprecation`.
      schema:
        type: string
        examples:
        - Thu, 01 Oct 2026 00:00:00 GMT
    RateLimit:
      description: 'Remaining quota for the current window, as an IETF structured field: `"default";r=<remaining>;t=<seconds until reset>`.'
      schema:
        type: string
        examples:
        - '"default";r=596;t=11'
    RateLimitPolicy:
      description: 'The quota this credential is subject to: `"default";q=<requests>;w=<window seconds>`.'
      schema:
        type: string
        examples:
        - '"default";q=600;w=60'
    RequestId:
      description: Unique id for this request. Quote it when reporting a problem.
      schema:
        type: string
        examples:
        - 8fe045fe-cb8a-4407-a44d-5df60385e522
    DeprecationLink:
      description: Present only on a deprecated operation. `<url>; rel="deprecation"` pointing at the migration notes.
      schema:
        type: string
        examples:
        - <https://crevio.co/docs/developer/guides/versioning>; rel="deprecation"
    Deprecation:
      description: Present only on a deprecated operation. Structured-field date (RFC 9745) — `@` followed by the Unix timestamp at which the operation became deprecated.
      schema:
        type: string
        examples:
        - '@1775001600'
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'API key in the format: Bearer {api_token}'
externalDocs:
  description: Crevio developer documentation
  url: https://crevio.co/docs/developer
x-mint:
  mcp:
    enabled: true
x-api-lifecycle:
  current_major_version: v1
  versioning_scheme: URL path
  deprecation_policy_url: https://crevio.co/docs/developer/guides/versioning
  minimum_notice_days: 183
  deprecation_headers:
  - Deprecation
  - Sunset
  - Link