cURL

curl --request POST \
  --url https://api.nohead.io/v1/projects/{project_id}/assets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "<string>",
  "content_type": "image/jpeg",
  "byte_size": 2
}
'

{
  "id": "ast_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "asset",
  "project_id": "<string>",
  "filename": "<string>",
  "alt": "<string>",
  "content_type": "image/png",
  "byte_size": 123,
  "width": 123,
  "height": 123,
  "status": "pending",
  "deleted_at": "2023-11-07T05:31:56Z",
  "purge_after": "2023-11-07T05:31:56Z",
  "image_url": "https://images.nohead.io/plain/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c",
  "preview_url": "<string>",
  "file_url": "https://files.nohead.io/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c",
  "media_url": "https://media.nohead.io/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c",
  "uploaded_at": "2023-11-07T05:31:56Z",
  "created_at": "2026-09-27T12:00:00.000Z",
  "updated_at": "2026-09-27T12:00:00.000Z",
  "upload": {
    "method": "PUT",
    "url": "<string>",
    "headers": {},
    "expires_at": "2026-09-27T12:00:00.000Z"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "Record validation failed",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "field": "title",
        "code": "required",
        "message": "is required"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

Assets

Start an upload

Step 1 of uploading a file. Returns the pending asset with its upload: send the file’s bytes with upload.method to upload.url, with upload.headers, before upload.expires_at. The bytes go directly to storage, not through this API. Then call POST /v1/assets/{asset_id}/complete.

content_type and byte_size must be the file’s; storage refuses another content type and completion refuses another size. A file larger than the plan allows (10 MB on Free, 100 MB on paid plans) is refused with 402 plan_limit_exceeded, whose details give its size (usage) and the limit (limit) for byte_size.

The file counts toward the organization’s storage from here on, while it uploads too. On plans where storage is a hard limit (Free), a file that would go over it is refused with 402 plan_limit_exceeded; on others, Nohead-Usage-Warning reports going over.

A project can have at most 100 uploads in progress (started within the upload’s lifetime, not yet completed or deleted); past that, 409 with too_many_uploads. Uploads never completed are removed after a day.

POST

projects

{project_id}

assets

cURL

curl --request POST \
  --url https://api.nohead.io/v1/projects/{project_id}/assets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "filename": "<string>",
  "content_type": "image/jpeg",
  "byte_size": 2
}
'

{
  "id": "ast_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
  "object": "asset",
  "project_id": "<string>",
  "filename": "<string>",
  "alt": "<string>",
  "content_type": "image/png",
  "byte_size": 123,
  "width": 123,
  "height": 123,
  "status": "pending",
  "deleted_at": "2023-11-07T05:31:56Z",
  "purge_after": "2023-11-07T05:31:56Z",
  "image_url": "https://images.nohead.io/plain/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c",
  "preview_url": "<string>",
  "file_url": "https://files.nohead.io/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c",
  "media_url": "https://media.nohead.io/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c",
  "uploaded_at": "2023-11-07T05:31:56Z",
  "created_at": "2026-09-27T12:00:00.000Z",
  "updated_at": "2026-09-27T12:00:00.000Z",
  "upload": {
    "method": "PUT",
    "url": "<string>",
    "headers": {},
    "expires_at": "2026-09-27T12:00:00.000Z"
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

{
  "error": {
    "type": "validation_error",
    "message": "Record validation failed",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "field": "title",
        "code": "required",
        "message": "is required"
      }
    ]
  }
}

{
  "error": {
    "type": "invalid_request",
    "message": "<string>",
    "request_id": "req_01J9ZQ3F8X5W2K7M4N6P0R1S2T",
    "details": [
      {
        "code": "<string>",
        "message": "<string>",
        "field": "<string>",
        "usage": 123,
        "limit": 123,
        "current_revision": 123,
        "record_id": "<string>",
        "draft_id": "<string>"
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Project-scoped API key, e.g. nohead_sk_k7fz0a9c3m2q_<secret>, or nohead_pk_… for a published-only key. Used by servers, CI, the CLI and coding agents.

Headers

Idempotency-Key

string

A unique value (1-255 printable ASCII characters) that makes retrying this request safe. The first response (below 500) is stored for 24 hours per user or API key; retries with the same key and the same request get it again with an Idempotent-Replayed: true header. The same key with a different request is refused with 400; a retry while the first request is still running gets 409.

Required string length: 1 - 255

Nohead-Client

string

First-party client identifier recorded in history (e.g. cli/0.3.1). Informational only.

Path Parameters

project_id

string

required

Body

application/json

filename

string

required

Maximum string length: 255

content_type

string

required

Example:

"image/jpeg"

byte_size

integer

required

Exact size of the file in bytes, at most the plan's largest upload (10 MB on Free, 100 MB on paid plans).

Required range: x >= 1

Response

The pending asset, with where to upload it.

A new asset with where to upload its file, returned only when it is created.

string

required

Example:

"ast_01J9ZQ3F8X5W2K7M4N6P0R1S2T"

object

any

required

project_id

string

required

filename

string

required

The filename, any Unicode, as uploaded unless renamed since. Downloads use it.

alt

string | null

required

Alternative text, saying what an image shows; null until set. The default wherever the asset is used.

Maximum string length: 1000

content_type

string

required

Example:

"image/png"

byte_size

integer

required

width

integer | null

required

Pixel width, for images.

height

integer | null

required

status

enum<string>

required

pending until the upload is completed; only ready assets can be used in records.

Available options:

pending,

ready,

failed

deleted_at

string<date-time> | null

required

When the asset was deleted; null unless it is.

purge_after

string<date-time> | null

required

When a deleted asset and its file are removed for good, unless restored or purged first.

image_url

string<uri> | null

required

The URL of the whole image, for ready images (JPEG, PNG, GIF, WebP, AVIF or SVG), deleted ones included until they are purged; null otherwise. Image URLs are open and never expire. An SVG is served as SVG without its scripts, unless a format such as @webp rasterizes it. For a rendition, write imgproxy processing options before /plain/, and a format after @: for example https://images.nohead.io/rs:fill:800:600/g:sm/plain/…@webp. Renditions are at most 4096 pixels a side, from originals of at most 50 megapixels. Options that would return the file as stored (raw, skip_processing, strip_metadata) are refused.

Example:

"https://images.nohead.io/plain/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c"

preview_url

string<uri> | null

required

The URL of a small rendition (fits in 640×640, WebP), for ready images and SVGs (rasterized), deleted ones included until they are purged; null otherwise.

file_url

string<uri> | null

required

The URL of the file as uploaded, for ready assets of any type, deleted ones included until they are purged; null otherwise. It downloads the file under its filename (a rename applies within a minute or so), is open and never expires, and is cached on a CDN.

Example:

"https://files.nohead.io/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c"

media_url

string<uri> | null

required

The URL that plays a ready video or audio file inline, for <video> and <audio> (with range requests, so players can seek), deleted ones included until they are purged: MP4, QuickTime, M4A, 3GP, WebM, Matroska, MP3, AAC, FLAC, WAV and Ogg (whose content is checked when the upload completes). Null for other types, which file_url downloads. Open, never expiring and cached on a CDN, like file_url.

Example:

"https://media.nohead.io/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c"

uploaded_at

string<date-time> | null

required

created_at

string<date-time>

required

ISO 8601 timestamp in UTC.

Example:

"2026-09-27T12:00:00.000Z"

updated_at

string<date-time>

required

ISO 8601 timestamp in UTC.

Example:

"2026-09-27T12:00:00.000Z"

upload

object

required

Show child attributes