Skip to content
Keliplay Docs

Import a file from a URL

POST
/v1/tenant/assets/import
curl --request POST \
  --url https://api.keliplay.com/v1/tenant/assets/import \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "url": "https://www.example.com/images/autumn-banner.png", "folderId": "0192f3a1-0000-7000-8000-0000000f1001" }'

Copies a file from a public https URL into your library. The copy happens in the background: the response is 202 with a pending file. Check progress with GET /v1/tenant/assets/imports.

Permission: assets.manage. Plan feature: Import from URL. Rate limit: 10 requests per minute and 200 per hour.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
url
required
string
>= 1 characters <= 2048 characters
filename

Defaults to the last part of the URL path.

string
>= 1 characters <= 200 characters
folderId
string | null
<= 64 characters
Example
{
  "url": "https://www.example.com/images/autumn-banner.png",
  "folderId": "0192f3a1-0000-7000-8000-0000000f1001"
}

Responses

Section titled “Responses”

202

Section titled “202”

The import has started.

Media typeapplication/json
object
asset
required

A file in your media library.

object
id
required
string
url
required

Where the file is served from. Use it in configs, themes and pages.

string format: uri
filename
required
string
contentType
required
string
sizeBytes

Set once the upload is confirmed.

integer | null
folderId
required
string | null
sourceUrl

The URL an imported file came from.

string | null
importStatus

Null for uploaded files.

string | null
Allowed values: pending failed done
importError
string | null
importAttempts
integer
createdAt
required
string format: date-time
updatedAt
string format: date-time
confirmedAt

When the file became available. Null while it is still uploading or importing.

string | null format: date-time
Example
{
  "asset": {
    "id": "0192f3a1-0000-7000-8000-0000000f2002",
    "url": "https://cdn.example.com/media/autumn-banner.png",
    "filename": "autumn-banner.png",
    "contentType": "application/octet-stream",
    "sizeBytes": null,
    "folderId": "0192f3a1-0000-7000-8000-0000000f1001",
    "sourceUrl": "https://www.example.com/images/autumn-banner.png",
    "importStatus": "pending",
    "importError": null,
    "importAttempts": 0,
    "createdAt": "2026-10-05T10:00:00.000Z",
    "updatedAt": "2026-10-05T10:00:00.000Z",
    "confirmedAt": null
  }
}

Headers

Section titled “Headers”
X-RateLimit-Limit
integer

Requests allowed in the current window.

X-RateLimit-Remaining
integer

Requests left in the current window.

400

Section titled “400”

The request is not valid. details lists each field that failed, where there is one.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request json.",
    "details": [
      {
        "path": "name",
        "message": "Too small, expected string to have >=1 characters"
      }
    ]
  }
}

401

Section titled “401”

The API key is missing, malformed or revoked.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or revoked API key."
  }
}

402

Section titled “402”

Your plan does not include this feature, or you have reached a plan limit.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "upgrade_required",
    "message": "Rewards is not included in your plan. Ask whoever manages your account to add it."
  }
}

403

Section titled “403”

The API key does not carry the permission this needs, or the request is not allowed.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "forbidden",
    "message": "Your role does not allow this (draws.run)."
  }
}

404

Section titled “404”

Nothing with that id exists in your account.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "not_found",
    "message": "Channel 0192f3a1-0000-7000-8000-00000000c009 not found."
  }
}

429

Section titled “429”

Rate limit exceeded. Wait for Retry-After seconds.

Media typeapplication/json
object
error
required
object
code
required

Stable and safe to branch on.

  • invalid_request (400): the request is not valid.
  • unauthorized (401): missing, malformed or revoked API key.
  • upgrade_required (402): not in your plan, or a plan limit is reached.
  • forbidden (403): the key lacks a permission, or the action is not allowed.
  • not_found (404): nothing with that id in your account.
  • conflict (409): clashes with the current state.
  • confirmation_required (409): repeat with confirm=true. Folder deletion only.
  • rate_limited (429): wait for Retry-After seconds.
  • internal_error (500) and service_unavailable (503): try again later.
string
Allowed values: invalid_request unauthorized upgrade_required forbidden not_found conflict confirmation_required rate_limited internal_error service_unavailable
message
required

Written for a person. May change; do not parse it.

string
details
One of:
Array<object>
object
path
required

The failing field, dot separated, such as prize.label.

string
message
required
string
Example
{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded: 30 requests per 60s."
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before trying again.

Product tour, pricing and demos: keliplay.com