Docs
Social

Upload a picture or video for a post

POSThttps://api.norreach.app/v1/social/uploads

Reserves a place for one file in the workspace's media and answers a single-use upload address (valid for 2 hours): PUT the file's bytes there with the given Content-Type, then put media_url in a version's media_urls. JPEG, PNG, WebP or GIF pictures up to 10 MB, MP4 videos up to 50 MB. The upload address is a secret — don't log or share it.

⚠ social:publishRole must allow: social.publishOperation id: create_social_upload
POST/social/uploads
curl -X POST "https://api.norreach.app/v1/social/uploads" \
  -H "Authorization: Bearer $NORREACH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "image/jpeg",
  "size_bytes": 482113,
  "filename": "nurses.jpg"
}'
Upload a picture or video for a post
{
  "object": "social_upload",
  "media_url": "https://media.example.com/social-media/6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/2f3e4d5c-6b7a-4c8d-9e0f-1a2b3c4d5e6f.jpg",
  "upload": {
    "method": "PUT",
    "url": "https://media.example.com/upload/sign/social-media/6a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d/2f3e4d5c-6b7a-4c8d-9e0f-1a2b3c4d5e6f.jpg?token=…",
    "headers": {
      "Content-Type": "image/jpeg"
    },
    "expires_at": "2026-11-05T11:12:33.120Z"
  },
  "content_type": "image/jpeg",
  "max_bytes": 10485760
}

Authorizations

Authorizationstringheaderrequired

Bearer authentication: send Authorization: Bearer <key>, with an API key or an OAuth access token. The key needs the scope social:publish. API keys and scopes

Body

application/json

content_typeenumrequired

image/jpeg, image/png, image/webp, image/gif or video/mp4.

One of:image/jpegimage/pngimage/webpimage/gifvideo/mp4
size_bytesintegerrequired

The file's size. Pictures up to 10 MB, videos up to 50 MB.

filenamestring

Only used in error messages.

Response

201application/json— Upload a picture or video for a post

object"social_upload"required
media_urlstringrequired

Where the file will be served once uploaded — put this in a variant's media_urls.

uploadobjectrequired

Send the file's bytes as the request body, with exactly these headers, before expires_at.

Show child attributes
upload.method"PUT"required
upload.urlstringrequired

A single-use, pre-signed address on NorReach's media store. Treat it as opaque and secret.

upload.headersobjectrequired
Show child attributes
upload.headers.Content-Typeenumrequired
One of:image/jpegimage/pngimage/webpimage/gifvideo/mp4
upload.expires_atstringrequired

RFC 3339 UTC timestamp with milliseconds.

content_typeenumrequired
One of:image/jpegimage/pngimage/webpimage/gifvideo/mp4
max_bytesintegerrequired

The largest file this type may be.

Errors

Errors are application/problem+json with a stable code.

StatusCodeMeaning
400bad_requestThe request couldn't be read.
400unknown_fieldThe request has a field this operation doesn't know.
401unauthorizedA valid API key is required.
403insufficient_scopeThis API key doesn't have the scope this operation needs.
403feature_not_enabledThe API isn't switched on for this workspace.
403role_forbiddenThe key's creator's role can't do this.
409idempotency_in_progressA request with this Idempotency-Key is still running.
413too_largeThe request body is too large.
422validation_failedThe request has invalid fields.
422idempotency_mismatchThis Idempotency-Key was used with a different request.
429rate_limitedToo many requests. Slow down and try again.
500server_errorSomething went wrong on our side.
503unavailableThe API isn't available right now. Try again shortly.