> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zerogen.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Declare an upload's external provenance

> Record untrusted external provenance on an eligible upload. This is not verified and starts no generation. Requires uploads:create and library:read when sources are declared. The JSON request body is limited to 512 KiB; a workflow is limited to 256 KiB serialized UTF-8.

Needs the `uploads:create` scope.



## OpenAPI

````yaml /openapi.json post /assets/{assetId}/declaration
openapi: 3.1.0
info:
  title: ZeroGen API
  version: v1
  description: >-
    Generate images and video with every model in ZeroGen from your own servers.
    Generated from the API's contracts by `npm run openapi` in apps/web; do not
    edit by hand.
servers:
  - url: https://api.zerogen.com/v1
security:
  - bearerAuth: []
tags:
  - name: Account
    description: The calling key and the organization's balance.
  - name: Models
    description: The models an organization can run and their schemas.
  - name: Runs
    description: Quote, create, read, list and cancel runs.
  - name: Uploads
    description: Upload files into the Library to use as inputs.
  - name: Projects
    description: The organization's projects.
  - name: Assets
    description: >-
      Search and read Library assets, their lineage and their folders; download
      their files; rename and favorite them.
  - name: Folders
    description: >-
      A project's folders: create, rename and move them, and add, move and
      remove their assets.
  - name: Labels
    description: 'Organization labels: manage them, and add them to assets or remove them.'
  - name: Naming presets
    description: A project's shared naming presets, for naming a run's outputs.
  - name: Skills
    description: The skills available to the key's owner.
paths:
  /assets/{assetId}/declaration:
    post:
      tags:
        - Assets
      summary: Declare an upload's external provenance
      description: >-
        Record untrusted external provenance on an eligible upload. This is not
        verified and starts no generation. Requires uploads:create and
        library:read when sources are declared. The JSON request body is limited
        to 512 KiB; a workflow is limited to 256 KiB serialized UTF-8.


        Needs the `uploads:create` scope.
      operationId: declareAssetUpload
      parameters:
        - name: assetId
          in: path
          required: true
          description: The asset's ID
          schema:
            type: string
        - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeclareUploadRequest'
      responses:
        '200':
          description: The declared upload.
          headers:
            Request-Id:
              $ref: '#/components/headers/Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            Idempotent-Replayed:
              $ref: '#/components/headers/Idempotent-Replayed'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetDeclaration'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: >-
        Makes retries safe: a retry with the same key and body returns the first
        response for 24 hours instead of repeating the work. Reusing a key with
        a different body returns 409.
      schema:
        type: string
        minLength: 1
        maxLength: 255
        pattern: ^[\x21-\x7e]+$
  schemas:
    DeclareUploadRequest:
      type: object
      properties:
        sources:
          description: >-
            Untrusted claims about the readable Library sources used outside
            ZeroGen.
          minItems: 1
          maxItems: 32
          type: array
          items:
            type: object
            properties:
              asset:
                type: string
                pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
                description: >-
                  An existing readable Library asset; this claim is not
                  verified.
              role:
                type: string
                enum:
                  - source
                  - initial-frame
                  - end-frame
                  - keyframe
                  - reference
                  - face-reference
                  - identity
                  - driver
                  - mask
            required:
              - asset
            additionalProperties: false
        tool:
          type: object
          properties:
            name:
              type: string
              minLength: 1
              maxLength: 40
              pattern: ^[a-z][a-z0-9-]*$
            version:
              type: string
              maxLength: 128
            integration:
              type: object
              properties:
                name:
                  type: string
                  minLength: 1
                  maxLength: 128
                version:
                  type: string
                  maxLength: 128
              required:
                - name
              additionalProperties: false
            models:
              maxItems: 32
              type: array
              items:
                type: string
                minLength: 1
                maxLength: 256
          required:
            - name
          additionalProperties: false
        workflow:
          type: object
          propertyNames:
            type: string
          additionalProperties:
            anyOf:
              - type: 'null'
              - type: string
              - type: number
              - type: boolean
              - type: array
                items: {}
              - type: object
                additionalProperties: {}
          description: Untrusted JSON workflow, limited to 262144 serialized UTF-8 bytes.
        prompt:
          type: string
          maxLength: 20000
        externalRef:
          type: object
          properties:
            system:
              type: string
              minLength: 1
              maxLength: 40
              pattern: ^[a-z][a-z0-9-]*$
            id:
              type: string
              minLength: 1
              maxLength: 256
          required:
            - system
            - id
          additionalProperties: false
        occurredAt:
          type: string
          format: date-time
          pattern: >-
            ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
      additionalProperties: false
      required:
        - tool
    AssetDeclaration:
      type: object
      properties:
        assetId:
          type: string
        runId:
          type: string
        asset:
          type: object
          properties:
            id:
              type: string
            projectId:
              type: string
            name:
              type: string
              description: The asset's name in the Library; untrusted content
            type:
              type: string
              enum:
                - image
                - video
                - audio
                - model3d
            origin:
              type: string
              enum:
                - generated
                - upload
                - derived
              description: >-
                upload: added by a person or a URL import; generated: an output
                of a run; derived: made by a platform step, such as an extracted
                frame
            mimeType:
              type: string
            sizeBytes:
              anyOf:
                - type: integer
                  minimum: 0
                  maximum: 9007199254740991
                - type: 'null'
            width:
              anyOf:
                - type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                - type: 'null'
            height:
              anyOf:
                - type: integer
                  exclusiveMinimum: 0
                  maximum: 9007199254740991
                - type: 'null'
            durationMs:
              anyOf:
                - type: integer
                  minimum: 0
                  maximum: 9007199254740991
                - type: 'null'
            favorite:
              description: The organization's shared favorite
              type: boolean
            labels:
              type: array
              items:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
                required:
                  - id
                  - name
                additionalProperties: false
            runId:
              description: The run that made it, if any
              type:
                - string
                - 'null'
            outputIndex:
              anyOf:
                - type: integer
                  minimum: 0
                  maximum: 9007199254740991
                - type: 'null'
            createdBy:
              anyOf:
                - $ref: '#/components/schemas/Creator'
                - type: 'null'
              description: >-
                Who made it: the run's creator for a generated or derived asset,
                the uploader for an upload; null when ZeroGen recorded no one
            createdVia:
              anyOf:
                - type: string
                  enum:
                    - web
                    - agent
                    - mcp
                    - api
                - type: 'null'
              description: >-
                Where it was made: web (the ZeroGen app), agent (ZeroGen's
                Agent), mcp (an MCP client) or api (an API key); null with
                createdBy
            declared:
              anyOf:
                - type: object
                  properties:
                    tool:
                      type: object
                      properties:
                        name:
                          type: string
                        version:
                          type: string
                        integration:
                          type: object
                          properties:
                            name:
                              type: string
                            version:
                              type: string
                          required:
                            - name
                          additionalProperties: false
                        models:
                          type: array
                          items:
                            type: string
                      required:
                        - name
                      additionalProperties: false
                    externalRef:
                      type: object
                      properties:
                        system:
                          type: string
                        id:
                          type: string
                      required:
                        - system
                        - id
                      additionalProperties: false
                    occurredAt:
                      type: string
                      format: date-time
                      pattern: >-
                        ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
                  required:
                    - tool
                  additionalProperties: false
                - type: 'null'
              description: >-
                Untrusted external upload provenance, or null when no
                declaration exists.
            createdAt:
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z))$
            webUrl:
              description: >-
                Opens the asset's Library review in ZeroGen, on your
                organization's host, after sign-in. null for test keys, whose
                sandbox the app doesn't show
              type:
                - string
                - 'null'
          required:
            - id
            - projectId
            - name
            - type
            - origin
            - mimeType
            - sizeBytes
            - width
            - height
            - durationMs
            - favorite
            - labels
            - runId
            - outputIndex
            - createdBy
            - createdVia
            - declared
            - createdAt
            - webUrl
          additionalProperties: false
      required:
        - assetId
        - runId
        - asset
      additionalProperties: false
    Creator:
      type: object
      properties:
        id:
          type: string
          description: The user's ID, as GET /v1/me returns the key's own
        name:
          description: The name the person gave ZeroGen, or null; never an email address
          type:
            - string
            - 'null'
      required:
        - id
        - name
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Error'
      required:
        - error
      additionalProperties: false
    Error:
      type: object
      properties:
        code:
          type: string
          pattern: ^[a-z][a-z0-9_]{0,79}$
        message:
          type: string
        param:
          type: string
        retryable:
          type: boolean
        details:
          type: object
          propertyNames:
            type: string
          additionalProperties: {}
      required:
        - code
        - message
        - retryable
      additionalProperties: false
  headers:
    Request-Id:
      description: Identifies the request; quote it when contacting support.
      schema:
        type: string
    RateLimit-Limit:
      description: Requests the key may make in the current window.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the current window resets.
      schema:
        type: integer
    Idempotent-Replayed:
      description: >-
        true when this response replays an earlier request with the same
        Idempotency-Key.
      schema:
        type: string
        enum:
          - 'true'
    WWW-Authenticate:
      description: Bearer realm="ZeroGen API".
      schema:
        type: string
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
  responses:
    BadRequest:
      description: >-
        The request is malformed or invalid: invalid_request, validation_failed,
        model_unavailable or input_import_failed.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: 'invalid_api_key: the key is missing, revoked or expired.'
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        WWW-Authenticate:
          $ref: '#/components/headers/WWW-Authenticate'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: >-
        permission_denied: the key lacks the scope this endpoint needs, the
        request came from a browser, or the API isn't enabled for the
        organization.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    NotFound:
      description: >-
        not_found: no such resource for this caller, including a projectId the
        caller can't use.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Conflict:
      description: >-
        idempotency_conflict: the Idempotency-Key was used for a different
        request. idempotency_in_progress: the first request with this key hasn't
        finished. invalid_state: the request can't go ahead as things stand,
        such as a run that needs a person's approval in ZeroGen.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    PayloadTooLarge:
      description: >-
        The request body is larger than this endpoint's limit: 128 KiB by
        default, or 512 KiB for `POST /uploads` and `POST
        /assets/{assetId}/declaration`.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    UnsupportedMediaType:
      description: Send the body as application/json.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: >-
        rate_limited: the key or its owner is over the rate limit, or the
        organization is at its running cap. Retry after Retry-After seconds.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalError:
      description: 'internal: something went wrong. Retry.'
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    ServiceUnavailable:
      description: >-
        unavailable or pricing_unavailable: API keys, billing or pricing can't
        be reached right now. Retry.
      headers:
        Request-Id:
          $ref: '#/components/headers/Request-Id'
        RateLimit-Limit:
          $ref: '#/components/headers/RateLimit-Limit'
        RateLimit-Remaining:
          $ref: '#/components/headers/RateLimit-Remaining'
        RateLimit-Reset:
          $ref: '#/components/headers/RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'A ZeroGen API key: zg_ for a live key, zg_test_ for a test key.'

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.