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

# Plan adding assets to a project (the assets_add dry run)

> Per item: ready (files with URLs and hashes), pending (conversion queued; call again to poll) or failed (AS-215 with alternatives). Writes nothing to a project; starts conversion for unprepared items.



## OpenAPI

````yaml /api-reference/openapi.json post /assets/plan
openapi: 3.1.0
info:
  title: Patch API
  version: 1.0.0
  description: >-
    The public API behind patch.gg, the desktop app and pch. Changes within v1
    are additive only. Errors are { error: { code, message, details } }; branch
    on code.
servers:
  - url: https://patch.gg/api/v1
security: []
paths:
  /assets/plan:
    post:
      tags:
        - Assets
      summary: Plan adding assets to a project (the assets_add dry run)
      description: >-
        Per item: ready (files with URLs and hashes), pending (conversion
        queued; call again to poll) or failed (AS-215 with alternatives). Writes
        nothing to a project; starts conversion for unprepared items.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssetPlanRequest'
      responses:
        '200':
          description: The plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AssetPlan'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Not signed in
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    AssetPlanRequest:
      type: object
      properties:
        items:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                minLength: 1
              as:
                type: string
                description: The name in code; suggested if left out
              needs:
                type: array
                items:
                  type: string
                example:
                  - collision
              variant:
                type: string
                description: '"auto" (default) or a variant name'
            required:
              - id
          minItems: 1
          maxItems: 50
        runtime:
          type: string
          example: patch-web@1
        delivery:
          type: string
          enum:
            - reference
            - vendor
      required:
        - items
    AssetPlan:
      type: object
      properties:
        plan_id:
          type: string
        runtime:
          type: string
        delivery:
          type: string
          enum:
            - reference
            - vendor
        state:
          type: string
          enum:
            - ready
            - pending
            - failed
        items:
          type: array
          items:
            anyOf:
              - type: object
                properties:
                  id:
                    type: string
                  as:
                    type: string
                  type:
                    type:
                      - string
                      - 'null'
                  state:
                    type: string
                    enum:
                      - ready
                  title:
                    type: string
                  variant:
                    type: string
                  version:
                    type:
                      - string
                      - 'null'
                  files:
                    type: array
                    items:
                      type: object
                      properties:
                        role:
                          type: string
                        name:
                          type: string
                        sha256:
                          type: string
                        size:
                          type: number
                        content_type:
                          type: string
                        url:
                          type:
                            - string
                            - 'null'
                        path:
                          type: string
                      required:
                        - role
                        - name
                        - sha256
                        - size
                        - content_type
                        - url
                        - path
                  capabilities:
                    type: object
                    properties:
                      runtime:
                        type: string
                      keeps:
                        type: array
                        items:
                          type: string
                      dropped:
                        type: array
                        items:
                          type: object
                          properties:
                            capability:
                              type: string
                            reason:
                              type: string
                          required:
                            - capability
                            - reason
                    required:
                      - runtime
                      - keeps
                      - dropped
                  license:
                    $ref: '#/components/schemas/AssetLicense'
                  credit:
                    type: string
                  source:
                    type: object
                    properties:
                      name:
                        type: string
                      url:
                        type: string
                    required:
                      - name
                      - url
                  ai:
                    type: boolean
                  facts:
                    type: object
                    additionalProperties: {}
                  usage:
                    type: string
                required:
                  - id
                  - as
                  - type
                  - state
                  - title
                  - variant
                  - version
                  - files
                  - capabilities
                  - license
                  - credit
                  - source
                  - ai
                  - facts
                  - usage
              - type: object
                properties:
                  id:
                    type: string
                  as:
                    type: string
                  type:
                    type:
                      - string
                      - 'null'
                  state:
                    type: string
                    enum:
                      - pending
                  prep:
                    type: object
                    properties:
                      state:
                        type: string
                        enum:
                          - indexed
                          - converting
                          - ready
                          - failed
                      eta_s:
                        type: number
                      error:
                        type: string
                    required:
                      - state
                required:
                  - id
                  - as
                  - type
                  - state
                  - prep
              - type: object
                properties:
                  id:
                    type: string
                  as:
                    type: string
                  type:
                    type:
                      - string
                      - 'null'
                  state:
                    type: string
                    enum:
                      - failed
                  code:
                    type: string
                  reason:
                    type: string
                  alternatives:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        title:
                          type: string
                        prep:
                          type: string
                          enum:
                            - indexed
                            - converting
                            - ready
                            - failed
                      required:
                        - id
                        - title
                        - prep
                required:
                  - id
                  - as
                  - type
                  - state
                  - code
                  - reason
                  - alternatives
        warnings:
          type: array
          items:
            type: object
            properties:
              code:
                type: string
              id:
                type: string
              msg:
                type: string
            required:
              - code
              - id
              - msg
        credits:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              license:
                type: string
              credit:
                type: string
            required:
              - id
              - license
              - credit
        licenses:
          type: array
          items:
            $ref: '#/components/schemas/AssetLicense'
        poll_after_s:
          type: number
      required:
        - plan_id
        - runtime
        - delivery
        - state
        - items
        - warnings
        - credits
        - licenses
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: version_exists
            message:
              type: string
            details: {}
          required:
            - code
            - message
      required:
        - error
    AssetLicense:
      type: object
      properties:
        spdx:
          type: string
        name:
          type: string
        url:
          type: string
        duties:
          type: array
          items:
            type: string
            enum:
              - attribute
              - link-license
              - indicate-changes
              - no-endorsement
              - no-added-restrictions
        text_url:
          type: string
      required:
        - spdx
        - name
        - url
        - duties
        - text_url

````

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