---
title: "Create an asset"
method: POST
path: "/api/v1/assets"
tags: ["assets"]
---

# Create an asset

`POST /api/v1/assets`

## Request

- Base URL: `https://api.growomat.com`
- URL: `https://api.growomat.com/api/v1/assets`
- Auth: HTTP bearer

Registers an image or video by public URL. The asset is stored as a pointer to that URL and is `READY` immediately; the bytes are fetched when a sync needs them. Attach it to a campaign, ad group or ad with the binding operations under *Campaign assets* and *Ad assets*.

**Errors**

- `400 VALIDATION_ERROR`: the body failed validation; `details.issues[]` names each field.

## Headers

- `X-Space-Id` string

## Request body

- AssetCreate: An asset registered by URL. Growomat stores a pointer to the URL and marks the asset `READY` at once; the bytes are fetched when a sync needs them.
  - `url` string, uri, required: A public http(s) URL of the image or video.
  - `name` string: Display name. Defaults to the file name in the URL.
  - `type` 'IMAGE' | 'LOGO' | 'VIDEO': What the asset is used as.
  - `mediaType` 'IMAGE' | 'VIDEO': The media kind. Derived from `type` when omitted (`IMAGE` for `IMAGE` and `LOGO`, `VIDEO` for `VIDEO`).
  - `youtubeVideoId` string: For video assets: the YouTube video id. Videos are referenced, never hosted or transcoded by Growomat.
  - `contentType` string: MIME type. Inferred from the URL when omitted.
  - `sizeBytes` integer: File size in bytes, when known.
  - `width` integer: Width in pixels, when known.
  - `height` integer: Height in pixels, when known.
  - `tags` string[]: Free-form tags for finding the asset later.
  - `altText` string: Alternative text describing the image.
  - `metadata` object: Anything else you want to keep with the asset.

## Response `200`

OK. The result is in `data`. List responses also carry `meta` with `nextCursor` and `total`.

- SuccessEnvelope: The shape of every successful response.
  - `data` unknown, required
  - `meta` object: Present on list responses.
    - `nextCursor` union: Pass as `cursor` to get the next page. `null` on the last page.
      - string
      - number
    - `total` integer: Number of items in this page.

## Other responses

- `201`: Created. The new resource is in `data`.
- `400`: The request is malformed or fails validation. `error.code` is `VALIDATION_ERROR` (with `details.issues[]` naming each field), `INVALID_REQUEST` (the body is not valid JSON or has the wrong shape), or one of the specific codes listed in this operation's description.
- `401`: The bearer token is missing, invalid, expired or revoked (`INVALID_TOKEN`).
- `403`: The token lacks the scope this operation needs (`INSUFFICIENT_SCOPE`), the plan is read-only (`READ_ONLY_MODE`), or the caller is not a member of the Space named in `X-Space-Id` (`NOT_A_MEMBER`).
- `404`: No such resource in the active Space (`NOT_FOUND`), or `X-Space-Id` names a Space that does not exist (`SPACE_NOT_FOUND`).
- `409`: The request conflicts with the current state, for example a delete blocked by dependents or a sync already running. This operation's description names the `error.code` values it can return.
- `429`: Too many requests (`RATE_LIMITED`). Wait for the number of seconds in the `Retry-After` header, then retry.

---

[API](https://skmtc.dev/growomat/apis/growomat-public-api.md) · [All operations](https://skmtc.dev/growomat/apis/growomat-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/growomat/apis/growomat-public-api/revisions/f02611b531aa?raw)