Import a picture into the library

POST

/v1/assets/import

curl --request POST \
  --url https://api.pixonaut.app/v1/assets/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "categoryId": "cat_4f2a9c1e", "name": "Summer logo", "tags": [ "summer", "logo" ], "url": "https://cdn.example.com/brand/summer-logo.png" }'

Operation ID: assets.import

Saves a picture to the library in one call, from a public url this server fetches or as base64 data (up to 655360 bytes), with its name, tags and category. It is held to an upload’s limits: its type read from its bytes, its size, its pixels and the tenant’s storage quota.

Authorizations

• secretKey

Request Body^required

Media typeapplication/json

object

categoryId

The category to put it in: its id, as list_asset_categories returns it. Left out, it is in none.

string

>= 1 characters <= 64 characters

data

The picture’s bytes, base64, at most 655360 bytes before encoding; a larger one is sent by url. Give this or url.

string

<= 873814 characters /^[A-Za-z0-9+/]*={0,2}$/

name

The picture’s name in the library, e.g. Summer logo.

string

>= 1 characters <= 200 characters

tags

The picture’s tags: lowercase words, e.g. summer, logo. At most 100.

Array<string>

<= 100 items

url

Where to fetch the picture: a public http(s) URL answering with the image itself. Give this or data.

string format: uri

<= 2048 characters

Examples

Exampleexample

Example

{
  "categoryId": "cat_4f2a9c1e",
  "name": "Summer logo",
  "tags": [
    "summer",
    "logo"
  ],
  "url": "https://cdn.example.com/brand/summer-logo.png"
}

Responses

201

The picture is in the library

Media typeapplication/json

object

assetId

required

string

categoryId

required

string | null

heightPx

required

number

name

required

string | null

tags

required

Array<string>

widthPx

required

number

Examples

Exampleexample

Example

{
  "assetId": "up_7a3e9b102c4d4e5f9a6b1c2d",
  "categoryId": "cat_4f2a9c1e",
  "heightPx": 1600,
  "name": "Summer logo",
  "tags": [
    "summer",
    "logo"
  ],
  "widthPx": 2400
}

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.

401

Refused: unauthorized

Media typeapplication/json

object

error

required

string

Examples

Exampleunauthorized

unauthorized

{
  "error": "unauthorized"
}

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.

403

Refused: origin_forbidden, forbidden, feature_disabled, workspace_suspended

Media typeapplication/json

object

error

required

string

feature

The feature the tenant does not have. Always sent with feature_disabled.

string

Examples

feature_disabled

{
  "error": "feature_disabled",
  "feature": "api"
}

forbidden

{
  "error": "forbidden"
}

origin_forbidden

{
  "error": "origin_forbidden"
}

workspace_suspended

{
  "error": "workspace_suspended"
}

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.

422

Refused: size_mismatch, unsupported_mime, animation_not_supported, not_a_valid_image, pixel_dimensions_too_large, size_out_of_bounds, invalid_tag, unknown_category, url_refused, payload_too_large, invalid_input

Media typeapplication/json

object

allowed

Always sent with unsupported_mime.

Array<string>

bytes

Sent with payload_too_large.

number

error

required

string

heightPx

Always sent with pixel_dimensions_too_large.

number

host

Sent with url_refused.

string

maxBytes

Always sent with size_out_of_bounds, payload_too_large.

number

maxEdgePx

Sent with pixel_dimensions_too_large.

number

maxPixels

Sent with pixel_dimensions_too_large.

number

reason

Always sent with url_refused.

string

tag

Always sent with invalid_tag.

string

widthPx

Always sent with pixel_dimensions_too_large.

number

Examples

animation_not_supported

{
  "error": "animation_not_supported"
}

invalid_input

{
  "error": "invalid_input"
}

invalid_tag

{
  "error": "invalid_tag",
  "tag": "string"
}

not_a_valid_image

{
  "error": "not_a_valid_image"
}

payload_too_large

{
  "error": "payload_too_large",
  "maxBytes": 0
}

pixel_dimensions_too_large

{
  "error": "pixel_dimensions_too_large",
  "heightPx": 0,
  "widthPx": 0
}

size_mismatch

{
  "error": "size_mismatch"
}

size_out_of_bounds

{
  "error": "size_out_of_bounds",
  "maxBytes": 0
}

unknown_category

{
  "error": "unknown_category"
}

unsupported_mime

{
  "allowed": [
    "string"
  ],
  "error": "unsupported_mime"
}

url_refused

{
  "error": "url_refused",
  "reason": "scheme"
}

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.

429

Refused: rate_limited

Media typeapplication/json

object

error

required

string

Examples

Examplerate_limited

rate_limited

{
  "error": "rate_limited"
}

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.

500

Refused: preview_failed, import_failed, db_error. A request that failed unexpectedly answers as text instead.

object

error

required

string

Examples

db_error

{
  "error": "db_error"
}

import_failed

{
  "error": "import_failed"
}

preview_failed

{
  "error": "preview_failed"
}

string

Allowed value: Internal Server Error

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.

502

Refused: fetch_failed

Media typeapplication/json

object

error

required

string

status

number

timedOut

boolean

Examples

Examplefetch_failed

fetch_failed

{
  "error": "fetch_failed"
}

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.

503

Refused: lock_timeout

Media typeapplication/json

object

error

required

string

Examples

Examplelock_timeout

lock_timeout

{
  "error": "lock_timeout"
}

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.

507

Refused: storage_quota_exceeded. The tenant’s storage quota would be exceeded. usedBytes and quotaBytes are left out for a publishable key.

Media typeapplication/json

object

error

required

string

quotaBytes

Always sent with storage_quota_exceeded.

number

usedBytes

Always sent with storage_quota_exceeded.

number

Examples

storage_quota_exceeded

{
  "error": "storage_quota_exceeded"
}

storage_quota_exceeded (usedBytes, quotaBytes)

{
  "error": "storage_quota_exceeded",
  "quotaBytes": 0,
  "usedBytes": 0
}

Headers

X-Request-Id

required

string

Every response names the request it answers in X-Request-Id: the id the request was sent with in that header, when it is well formed, else one the API gave it. Quote it when reporting a refusal or a failure: the API’s log lines for that request carry it.