API REFERENCE

PATCH /api/content/packs/{id}

On this page

PATCH/api/content/packs/{id}

Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes.

Authentication

x-api-key in header

bearerAuth bearer

Request

cURL

curl --request PATCH \
  --url 'https://api.recoupable.dev/api/content/packs/YOUR_ID' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "expected_revision": 0,
  "idempotency_key": "string",
  "brief": {
    "artist_name": "string",
    "artist_account_id": "YOUR_ID",
    "song_title": "string",
    "recording_version": "string",
    "audio_url": "string",
    "audio_start_seconds": 0,
    "occasion": "new_release",
    "original_release_date": "string",
    "campaign_date": "string",
    "primary_action": "listen",
    "destination_url": "string",
    "audience": "string",
    "song_summary": "string",
    "lyrics_excerpt": "string",
    "creative_direction": "string",
    "allow_creative_defaults": false,
    "reference_image_urls": [],
    "constraints": [],
    "platforms": [
      "instagram",
      "tiktok"
    ],
    "context_brief_id": "YOUR_ID",
    "evidence": [],
    "creative_context": {
      "starting_point": "established",
      "working_mode": "autonomous",
      "references": [],
      "directions": []
    }
  }
}'

Replace the YOUR_ placeholders with your values. Required query parameters are included; optional parameters are listed below.

Try it

Fill in the fields, send the request from your browser, and read the live response. The curl below updates as you type.

API keyx-api-key header

Kept in this browser tab only and cleared when it closes.

idpath · stringrequired

Request bodyapplication/json

cURL for this request

curl --request PATCH \
  --url 'https://api.recoupable.dev/api/content/packs/{id}' \
  --header 'Content-Type: application/json' \
  --data '{
  "expected_revision": 0,
  "idempotency_key": "string",
  "brief": {
    "artist_name": "string",
    "artist_account_id": "YOUR_ID",
    "song_title": "string",
    "recording_version": "string",
    "audio_url": "string",
    "audio_start_seconds": 0,
    "occasion": "new_release",
    "original_release_date": "string",
    "campaign_date": "string",
    "primary_action": "listen",
    "destination_url": "string",
    "audience": "string",
    "song_summary": "string",
    "lyrics_excerpt": "string",
    "creative_direction": "string",
    "allow_creative_defaults": false,
    "reference_image_urls": [],
    "constraints": [],
    "platforms": [
      "instagram",
      "tiktok"
    ],
    "context_brief_id": "YOUR_ID",
    "evidence": [],
    "creative_context": {
      "starting_point": "established",
      "working_mode": "autonomous",
      "references": [],
      "directions": []
    }
  }
}'

Parameters

Path parameters

idstringrequired

Request body required

application/json

organization_idstring

format: uuid · pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

expected_revisionintegerrequired

maximum: 9007199254740991

idempotency_keystringrequired

minLength: 1 · maxLength: 100 · pattern: ^[A-Za-z0-9._:-]+$

briefobjectrequired

Properties

artist_namestring

minLength: 1 · maxLength: 2000

artist_account_idstring

format: uuid · pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

song_titlestring

minLength: 1 · maxLength: 2000

recording_versionstring

minLength: 1 · maxLength: 2000

audio_urlstring

format: uri · maxLength: 4000

audio_start_secondsnumber

minimum: 0 · maximum: 1200

occasionstring · enum

Values: "new_release", "anniversary", "reissue", "remix", "rediscovery"

original_release_datestring

format: date · 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])))$

campaign_datestring

primary_actionstring

Default: "listen"

minLength: 1 · maxLength: 2000

destination_urlstring

format: uri · maxLength: 4000

audiencestring

minLength: 1 · maxLength: 2000

song_summarystring

minLength: 1 · maxLength: 2000

lyrics_excerptstring

maxLength: 1000

creative_directionstring

minLength: 1 · maxLength: 2000

allow_creative_defaultsboolean

Default: false

reference_image_urlsarray<string>

Default: []

maxItems: 5

Item properties

string

constraintsarray<string>

Default: []

maxItems: 12

Item properties

string

platformsarray<string · enum>

Default: ["instagram","tiktok"]

minItems: 1 · maxItems: 6

Item properties

string · enum · "instagram", "tiktok", "youtube", "facebook", "linkedin", "x"

context_brief_idstring

format: uuid · pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

evidencearray<object>

Default: []

maxItems: 20

Item properties

textstringrequired

minLength: 1 · maxLength: 2000

kindstring · enumrequired

Values: "customer_assertion", "source_observation", "creative_proposal"

source_urlstring

format: uri · maxLength: 4000

creative_contextobject

Optional saved creative state. Ids are unique within this brief, selections reference an existing direction, and each direction references existing manifest ids. Guided mode requires customer selection before final quote or generation. Selected production image references plus legacy reference_image_urls must contain at most five distinct URLs. Reference-only inputs never become production image inputs.

Properties

starting_pointstring · enumrequired

Values: "established", "rough_idea", "none"

working_modestring · enumrequired

Values: "autonomous", "guided"

Default: "autonomous"

referencesarray<object>required

Default: []

maxItems: 20

Item properties

idstringrequired

minLength: 1 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]+$

titlestringrequired

minLength: 1 · maxLength: 2000

urlstringrequired

format: uri · maxLength: 4000

media_typestring · enumrequired

Values: "image", "document", "link"

source_kindstring · enumrequired

Values: "recoup", "customer", "public", "generated"

usagestring · enumrequired

Values: "reference_only", "production"

Default: "reference_only"

directionsarray<object>required

Default: []

maxItems: 3

Item properties

idstringrequired

minLength: 1 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]+$

namestringrequired

minLength: 1 · maxLength: 120

conceptstringrequired

minLength: 1 · maxLength: 1200

palettearray<string>required

Default: []

maxItems: 8

Item properties

string

typographystring

minLength: 1 · maxLength: 200

reference_idsarray<string>required

Default: []

maxItems: 20

Item properties

string

board_urlstring

format: uri · maxLength: 4000

selectionobject

Properties

direction_idstringrequired

minLength: 1 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]+$

selected_bystring · enumrequired

Values: "customer", "agent"

decision_notestringrequired

minLength: 1 · maxLength: 2000

deliverablesobject

Default: {"videos":8,"quote_cards":4,"artwork":1,"carousels":1,"visualizers":1,"video_seconds":8}

Properties

videosinteger

Default: 8

minimum: 0 · maximum: 12

quote_cardsinteger

Default: 4

minimum: 0 · maximum: 8

artworkinteger

Default: 1

minimum: 0 · maximum: 2

carouselsinteger

Default: 1

minimum: 0 · maximum: 2

visualizersinteger

Default: 1

minimum: 0 · maximum: 3

video_secondsinteger

Default: 8

minimum: 5 · maximum: 15

Responses

200Current owned result; running is not completed.

application/json

jobobjectrequired

Properties

idstringrequired

format: uuid

revisionintegerrequired

minimum: 1

statusstring · enumrequired

Values: "draft", "needs_input", "ready_to_quote", "awaiting_approval", "running", "partial", "completed", "failed", "canceled"

briefobjectrequired

Properties

artist_namestring

minLength: 1 · maxLength: 2000

artist_account_idstring

format: uuid · pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

song_titlestring

minLength: 1 · maxLength: 2000

recording_versionstring

minLength: 1 · maxLength: 2000

audio_urlstring

format: uri · maxLength: 4000

audio_start_secondsnumber

minimum: 0 · maximum: 1200

occasionstring · enum

Values: "new_release", "anniversary", "reissue", "remix", "rediscovery"

original_release_datestring

campaign_datestring

primary_actionstring

Default: "listen"

minLength: 1 · maxLength: 2000

destination_urlstring

format: uri · maxLength: 4000

audiencestring

minLength: 1 · maxLength: 2000

song_summarystring

minLength: 1 · maxLength: 2000

lyrics_excerptstring

maxLength: 1000

creative_directionstring

minLength: 1 · maxLength: 2000

allow_creative_defaultsboolean

Default: false

reference_image_urlsarray<string>

Default: []

maxItems: 5

Item properties

string

constraintsarray<string>

Default: []

maxItems: 12

Item properties

string

platformsarray<string · enum>

Default: ["instagram","tiktok"]

minItems: 1 · maxItems: 6

Item properties

string · enum · "instagram", "tiktok", "youtube", "facebook", "linkedin", "x"

context_brief_idstring

format: uuid · pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

evidencearray<object>

Default: []

maxItems: 20

Item properties

textstringrequired

minLength: 1 · maxLength: 2000

kindstring · enumrequired

Values: "customer_assertion", "source_observation", "creative_proposal"

source_urlstring

format: uri · maxLength: 4000

creative_contextobject

Properties

starting_pointstring · enumrequired

Values: "established", "rough_idea", "none"

working_modestring · enumrequired

Values: "autonomous", "guided"

Default: "autonomous"

referencesarray<object>required

Default: []

maxItems: 20

Item properties

idstringrequired

minLength: 1 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]+$

titlestringrequired

minLength: 1 · maxLength: 2000

urlstringrequired

format: uri · maxLength: 4000

media_typestring · enumrequired

Values: "image", "document", "link"

source_kindstring · enumrequired

Values: "recoup", "customer", "public", "generated"

usagestring · enumrequired

Values: "reference_only", "production"

Default: "reference_only"

directionsarray<object>required

Default: []

maxItems: 3

Item properties

idstringrequired

minLength: 1 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]+$

namestringrequired

minLength: 1 · maxLength: 120

conceptstringrequired

minLength: 1 · maxLength: 1200

palettearray<string>required

Default: []

maxItems: 8

Item properties

string

typographystring

minLength: 1 · maxLength: 200

reference_idsarray<string>required

Default: []

maxItems: 20

Item properties

string

board_urlstring

format: uri · maxLength: 4000

selectionobject

Properties

direction_idstringrequired

minLength: 1 · maxLength: 80 · pattern: ^[A-Za-z0-9_-]+$

selected_bystring · enumrequired

Values: "customer", "agent"

decision_notestringrequired

minLength: 1 · maxLength: 2000

deliverablesobjectrequired

quoteobject | null

Quote id, fingerprint, revision, expiry, complete line_items, maximum_usd, credits, piece/file/caption counts and retry policy.

assetsarray<object>required

Item properties

object

readinessobjectrequired

Properties

readyboolean

missingarray<string>

Item properties

string

assumptionsarray<string>

Item properties

string

next_actionstringrequired

400Invalid input.

application/json

statusstringrequired

errorstringrequired

billingUrlstring

format: uri

401Authentication required.

application/json

statusstringrequired

errorstringrequired

billingUrlstring

format: uri

402Insufficient credits; use returned billingUrl.

application/json

statusstringrequired

errorstringrequired

billingUrlstring

format: uri

403Workspace access denied.

application/json

statusstringrequired

errorstringrequired

billingUrlstring

format: uri

404Owned resource not found.

application/json

statusstringrequired

errorstringrequired

billingUrlstring

format: uri

409Stale quote/revision, unresolved submission, budget/state conflict or required execution capability unavailable.

application/json

statusstringrequired

errorstringrequired

billingUrlstring

format: uri

Full specification

Download the OpenAPI file for complete schemas, constraints, and examples.

Download content.json

View operation source

json

{
  "operationId": "updateReleasePack",
  "description": "Release rollout pending; discover current host capabilities before execution. Update the draft using expected_revision; changed inputs invalidate prior quotes.",
  "security": [
    {
      "apiKeyAuth": []
    },
    {
      "bearerAuth": []
    }
  ],
  "responses": {
    "200": {
      "description": "Current owned result; running is not completed.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReleasePackResponse"
          }
        }
      }
    },
    "400": {
      "description": "Invalid input.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReleasePackError"
          }
        }
      }
    },
    "401": {
      "description": "Authentication required.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReleasePackError"
          }
        }
      }
    },
    "402": {
      "description": "Insufficient credits; use returned billingUrl.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReleasePackError"
          }
        }
      }
    },
    "403": {
      "description": "Workspace access denied.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReleasePackError"
          }
        }
      }
    },
    "404": {
      "description": "Owned resource not found.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReleasePackError"
          }
        }
      }
    },
    "409": {
      "description": "Stale quote/revision, unresolved submission, budget/state conflict or required execution capability unavailable.",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ReleasePackError"
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
        "type": "string",
        "format": "uuid"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/UpdateReleasePackRequest"
        }
      }
    }
  },
  "x-recoup-availability": "pending"
}