> ## Documentation Index > Fetch the complete documentation index at: https://docs.nohead.io/llms.txt > Use this file to discover all available pages before exploring further. # See where an asset is used > The undeleted records that use the asset, through an asset field or as an image in a rich text field, in their content or in their pending draft (whose merge needs the asset): how many, how many of them are published with it in their content, and the 10 most recently updated with the fields they use it in. Record history does not count. Needs `records:read` too, as it shows records; published-only API keys get `403`. ## OpenAPI ````yaml /openapi.json get /v1/assets/{asset_id}/usage openapi: 3.1.1 info: title: Nohead API version: 1.0.0 summary: Programmable content and data API. contact: name: Nohead email: hello@nohead.io url: https://nohead.io description: > The Nohead API manages projects, collections (your data models), their fields, and records (your content), with full version history. ## Authentication Send `Authorization: Bearer `. Servers, CI and agents use a project API key (`nohead_sk_...`, or `nohead_pk_...` for a published-only key; created in the web app under API keys) with scopes such as `records:read` or `schema:write`. Organization, project, member and API key management need a person signed in to the web app and are not available to API keys. ## Resources and IDs Every object has an `object` type, and every resource with an identity of its own an opaque, prefixed `id` (`col_`, `fld_`, `rec_`, ...). Record values live under `data`, keyed by each field's `key`. Timestamps are ISO 8601 in UTC. Deleting a record, collection, field, asset or webhook is soft: it can be restored until its `purge_after`. ## Lists Lists return `{ "data": [...], "meta": { "next_cursor", "has_more" } }`. Pass `limit` (1-100) and `cursor` to page, and `sort` (prefix `-` for descending). Records also take `filter[]=value`, `filter[published_at][exists]=true` and `expand=`. ## Errors Errors share one envelope: `{ "error": { "type", "message", "request_id", "details" } }`. `details` lists field-level problems as `{ "field", "code", "message" }`. Include the `request_id` when asking for support. ## Safe retries and concurrent edits Send `Idempotency-Key` on any `POST`, `PUT`, `PATCH` or `DELETE` to make retrying it safe: the first result is stored for 24 hours and returned again for the same request. Record responses carry the record's revision as an `ETag`; send it back as `If-Match` to update only if nobody changed the record in the meantime (`412` otherwise). ## History Every change to a record is a revision, attributed to the person or API key that made it: record revisions can be listed, diffed and reverted, and collections keep a schema history. Send `Nohead-Change-Note` to record why a change was made. Changes that rewrite existing values (such as a field's type) are explicit, previewable field migrations. How long revisions are kept depends on the organization's plan. Older ones are removed, but every record keeps its first revision and its last 10; `history_pruned_through` says how far history was removed. license: name: Proprietary identifier: LicenseRef-Proprietary servers: - url: https://api.nohead.io description: Production security: - apiKey: [] tags: - name: records x-group: Records description: Content entries, one at a time or many at once. - name: publishing x-group: Publishing description: Making records live, now or at a set time, and taking them down. - name: revisions x-group: Revisions description: A record's history, comparing two revisions, and going back to one. - name: drafts x-group: Drafts description: Changes to a record that wait to be merged into it, now or at a set time. - name: collections x-group: Collections description: User-defined data models. - name: schema-changes x-group: Schema changes description: A collection's schema history, and its schema at any version. - name: fields x-group: Fields description: Field definitions of a collection. - name: migrations x-group: Field migrations description: Explicit field changes that rewrite existing record values, with previews. - name: assets x-group: Assets description: Files stored for a project, uploaded directly to storage. - name: search x-group: Search description: Full-text search in collections and across a project. - name: webhooks x-group: Webhooks description: Event notifications sent to your URLs, and the secrets that sign them. - name: deliveries x-group: Webhook deliveries description: Each event sent to a webhook, its attempts, and retrying it. - name: audit x-group: Activity log description: The append-only trail of who changed what, through which client. - name: system x-group: System description: Service status, the caller, and its feature flags. paths: /v1/assets/{asset_id}/usage: parameters: - $ref: '#/components/parameters/AssetId' get: tags: - assets summary: See where an asset is used description: | The undeleted records that use the asset, through an asset field or as an image in a rich text field, in their content or in their pending draft (whose merge needs the asset): how many, how many of them are published with it in their content, and the 10 most recently updated with the fields they use it in. Record history does not count. Needs `records:read` too, as it shows records; published-only API keys get `403`. operationId: assets_usage responses: '200': description: Where the asset is used. content: application/json: schema: $ref: '#/components/schemas/AssetUsage' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' x-codeSamples: - lang: typescript label: TypeScript source: | import { Nohead } from "@nohead/sdk" const nohead = new Nohead() const result = await nohead.assets.usage("ast_01J9ZQ3F8X") - lang: python label: Python source: | from nohead import Nohead nohead = Nohead() result = nohead.assets.usage("ast_01J9ZQ3F8X") - lang: ruby label: Ruby source: | require "nohead" nohead = Nohead::Client.new result = nohead.assets.usage("ast_01J9ZQ3F8X") components: parameters: AssetId: name: asset_id in: path required: true schema: type: string example: ast_01J9ZQ3F8X5W2K7M4N6P0R1S2T schemas: AssetUsage: type: object additionalProperties: false required: - object - asset_id - records - published - uses properties: object: const: asset_usage asset_id: type: string records: type: integer minimum: 0 description: >- Undeleted records that use the asset, in their content or their draft. published: type: integer minimum: 0 description: >- Of those, the published ones whose content uses it (what sites show). uses: type: array maxItems: 10 description: The most recently updated records that use the asset. items: type: object additionalProperties: false required: - record - fields properties: record: $ref: '#/components/schemas/Record' fields: type: array minItems: 1 description: >- Keys of the record's fields that use the asset, in its content or its draft. items: type: string Record: type: object additionalProperties: false required: - id - object - collection_id - collection - published_at - revision - schema_version - deleted_at - purge_after - history_pruned_through - data - created_at - updated_at properties: id: type: string examples: - rec_01J9ZQ3F8X5W2K7M4N6P0R1S2T object: const: record collection_id: type: string collection: type: string description: The collection slug. published_at: $ref: '#/components/schemas/NullableTimestamp' description: When the record was published; null while it is unpublished. revision: type: integer description: Current revision number; also returned as the ETag. schema_version: type: integer history_pruned_through: type: - integer - 'null' description: >- Revisions up to this number (except revision 1) were removed by the plan's history retention. deleted_at: $ref: '#/components/schemas/NullableTimestamp' description: When the record was soft-deleted; null unless it is. purge_after: $ref: '#/components/schemas/NullableTimestamp' description: >- When a soft-deleted record is removed for good, unless restored first. data: $ref: '#/components/schemas/RecordData' expanded: type: object description: > Only with `expand`: what each requested relation, asset or rich text field points at, keyed by field key: records for relation fields, assets for asset fields. A single value is the object, or null when it no longer exists; a multiple value is a list of those that still exist. For a rich text field, the list of assets its images show, in document order, leaving out those that no longer exist. Expanded records are not expanded further. additionalProperties: anyOf: - $ref: '#/components/schemas/Record' - $ref: '#/components/schemas/Asset' - type: 'null' - type: array items: anyOf: - $ref: '#/components/schemas/Record' - $ref: '#/components/schemas/Asset' created_at: $ref: '#/components/schemas/Timestamp' updated_at: $ref: '#/components/schemas/Timestamp' Error: type: object additionalProperties: false required: - error properties: error: type: object additionalProperties: false required: - type - message - request_id properties: type: $ref: '#/components/schemas/ErrorType' message: type: string request_id: $ref: '#/components/schemas/RequestId' details: type: array items: $ref: '#/components/schemas/ErrorDetail' NullableTimestamp: type: - string - 'null' format: date-time RecordData: type: object description: > Field values keyed by field `key`. A rich text value is written as Markdown (GitHub Flavored, a string) or as a ProseMirror JSON document (`{"type": "doc", "content": [...]}`), and stored and read as the document (`rich_text` reads it as HTML or Markdown). Markdown is converted as closely as the vocabulary allows: headings below h3 become h3, task list items plain items, footnotes and raw HTML text. A document uses the web editor's vocabulary (Tiptap's StarterKit and tables) and nothing else; another name is refused with `invalid_format`, naming ours where one fits (`strong` is `bold`): - blocks: `paragraph`, `heading` (`level` 1-3), `blockquote`, `bulletList` and `orderedList` (`start`, `type`) of `listItem` (starting with a paragraph), `codeBlock` (`language`), `horizontalRule`, and `table` of `tableRow` of `tableHeader` or `tableCell` (`colspan`, `rowspan`, `colwidth`, `align`); any block may have `dir` (`auto`, `ltr`, `rtl`); - inline: `text` (non-empty) and `hardBreak`; - marks on text: `bold`, `italic`, `strike`, `underline`, `code` (alone), and `link` (`href`, and `target`, `rel`, `class`, `title`); a link's `href` is an `http`, `https`, `mailto`, `tel` or relative URL. An image of an asset is `{"type": "image", "attrs": {"asset_id": "ast_...", "alt": "..."}}` (in Markdown `![alt](ast_...)`, or the asset's `image_url`), between the document's blocks (not inside a list, quote or table), at most 100 per document (`too_many_images`); a newly shown image must be an uploaded JPEG, PNG, GIF, WebP, AVIF or SVG of the project (`invalid_reference`, `type_not_accepted`). `expand` embeds the assets, and published-only keys can read the images of published records. A record holds at most 2,000,000 bytes of values, all fields together (`too_large` on `data`); one already larger can still be edited without growing. additionalProperties: true examples: - title: Introducing Foo body: type: doc content: [] Asset: allOf: - $ref: '#/components/schemas/AssetProperties' unevaluatedProperties: false Timestamp: type: string format: date-time description: ISO 8601 timestamp in UTC. examples: - '2026-09-27T12:00:00.000Z' RequestId: type: string pattern: ^req_[A-Za-z0-9]+$ examples: - req_01J9ZQ3F8X5W2K7M4N6P0R1S2T ErrorType: type: string enum: - invalid_request - authentication_error - plan_limit_exceeded - authorization_error - not_found - conflict - precondition_failed - validation_error - rate_limited - internal_error - service_unavailable ErrorDetail: type: object additionalProperties: false required: - code - message properties: field: type: string description: Key of the offending field or parameter, when applicable. code: type: string description: Machine-readable error code, e.g. `required`. message: type: string usage: type: integer description: Current usage, for `plan_limit` details. limit: type: integer description: The plan's limit, for `plan_limit` details. current_revision: type: integer description: The resource's current revision, for `revision_mismatch` details. record_id: type: string description: The record that already has the value, for `taken` details. draft_id: type: string description: The record's draft, for `draft_exists` and `draft_pending` details. AssetProperties: type: object required: - id - object - project_id - filename - alt - content_type - byte_size - width - height - status - deleted_at - purge_after - image_url - preview_url - file_url - media_url - uploaded_at - created_at - updated_at properties: id: type: string examples: - ast_01J9ZQ3F8X5W2K7M4N6P0R1S2T object: const: asset project_id: type: string filename: type: string description: >- The filename, any Unicode, as uploaded unless renamed since. Downloads use it. alt: type: - string - 'null' maxLength: 1000 description: >- Alternative text, saying what an image shows; null until set. The default wherever the asset is used. content_type: type: string examples: - image/png byte_size: type: integer width: type: - integer - 'null' description: Pixel width, for images. height: type: - integer - 'null' status: type: string enum: - pending - ready - failed description: >- `pending` until the upload is completed; only `ready` assets can be used in records. deleted_at: $ref: '#/components/schemas/NullableTimestamp' description: When the asset was deleted; null unless it is. purge_after: $ref: '#/components/schemas/NullableTimestamp' description: >- When a deleted asset and its file are removed for good, unless restored or purged first. image_url: type: - string - 'null' format: uri description: > 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](https://docs.imgproxy.net/usage/processing) 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. examples: - >- https://images.nohead.io/plain/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c preview_url: type: - string - 'null' format: uri description: >- 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: type: - string - 'null' format: uri description: | 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. examples: - >- https://files.nohead.io/0199f5c2-7b1e-7c3a-9d4f-2a6b8c0e1f3d/0199f5c2-8a2d-7e4b-b1c3-5d7e9f1a2b4c media_url: type: - string - 'null' format: uri description: | The URL that plays a ready video or audio file inline, for `