Skip to main content
PATCH
/
models
/
{model_id}
Update one of the organization's models
curl --request PATCH \
  --url https://api.samsa.ai/public/v1/models/{model_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Renamed Model",
  "default_prompt": "A refined flat-design illustration in the Acme brand palette."
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "is_ready": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "category": "style",
  "thumbnail_url": "https://cdn.samsa.ai/models/…/thumbnail.webp?X-Amz-Signature=…",
  "reference_image_urls": [
    "<string>"
  ],
  "user_instruction": "Use for hero banners and social posts.",
  "default_prompt": "A bold flat-design illustration in the Acme brand palette.",
  "trigger_words": [
    "<string>"
  ]
}
Updates the editable fields of a model owned by your organization and returns the updated model. Only name and default_prompt are editable; ownership and privacy fields cannot be changed. Omit a field to leave it unchanged — do not send it as an explicit null. Unknown or other-organization ids return 404 not_found. Requires the models.write scope.

Authorizations

​
Authorization
string
header
required

Organization API key as a bearer token: Authorization: Bearer samsa_sk_....

Headers

​
authorization
string | null

Path Parameters

​
model_id
string<uuid>
required

Body

application/json

PATCH /models/{id} body — the publicly editable fields only (ADR §10, ticket §3).

Ownership / privacy fields (owner_id, private, organization_id) are intentionally NOT accepted. A field may be omitted (left unchanged) but must not be sent as an explicit null — mirroring ApiKeyUpdate.

​
name
string | null

New model name.

Required string length: 1 - 100
Example:

"Renamed Model"

​
default_prompt
string | null

New default prompt / capability description.

Maximum string length: 2000
Example:

"A refined flat-design illustration in the Acme brand palette."

Response

Successful Response

A single model with full detail — the GET /models/{id} body (ADR §10).

​
id
string<uuid>
required
​
name
string
required
Example:

"Acme Brand Style"

​
status
enum<string>
required

Creation status: pending, processing, completed, or failed.

Available options:
pending,
processing,
completed,
failed
Example:

"completed"

​
is_ready
boolean
required

True when the model is completed AND active — usable for generation.

Example:

true

​
created_at
string<date-time>
required
​
updated_at
string<date-time>
required
​
category
enum<string> | null

Model category — one of style, object, person, setting.

Available options:
style,
object,
person,
setting
Example:

"style"

​
thumbnail_url
string | null

Presigned, time-limited HTTPS thumbnail URL (null when the model has none).

Example:

"https://cdn.samsa.ai/models/…/thumbnail.webp?X-Amz-Signature=…"

​
reference_image_urls
string[]

Presigned, time-limited HTTPS URLs of the reference images used to create the model.

Example:
[
  "https://cdn.samsa.ai/models/…/ref-0.webp?X-Amz-Signature=…"
]
​
user_instruction
string | null

Free-text guidance for how to use the model.

Example:

"Use for hero banners and social posts."

​
default_prompt
string | null

The model's default prompt / capability description.

Example:

"A bold flat-design illustration in the Acme brand palette."

​
trigger_words
string[]

Trigger words associated with the model.

Example:
["acme"]