Skip to content
Metakip Docs

Upload An Image To A Page

POST
/pages/{pageId}/images
curl --request POST \
  --url https://app.metakip.com/api/v1/pages/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/images \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: multipart/form-data' \
  --form file=@file \
  --form alt=example

Uploads a JPEG, PNG, GIF, or WebP image, attaches it to the page, and returns stable Markdown for insertion. The maximum image size is 10 MB.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
pageId
required
string format: uuid

The UUID of the page.

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters <= 200 characters /\S/

Use the same key to retry the same request. Completed responses are replayed for 24 hours; incomplete reservations expire after 5 minutes.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typemultipart/form-data
object
file
required
string format: binary
alt
string
<= 500 characters

Responses

Section titled “Responses”

201

Section titled “201”

The managed image and Markdown reference.

Media typeapplication/json
object
id
required
string format: uuid
/^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$/
url
required
string
>= 1 characters
markdown
required
string
>= 1 characters
filename
required
string
>= 1 characters
originalName
required
string
>= 1 characters
mimeType
required
string
Allowed values: image/jpeg image/png image/gif image/webp
size
required
integer
<= 9007199254740991
Example
{
  "mimeType": "image/jpeg"
}

403

Section titled “403”

The API token is missing a required scope: pages:write.

Media typeapplication/json

Structured error returned when the request cannot be completed.

object
error
required

Error details for programmatic handling.

object
code
required

Stable error code.

string
message
required

Human-readable explanation.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example"
  }
}