Synupv1
Create a key
v1Resources/Media

Media

Read and upload a location's media library.

Returns the logo, photos, and videos on file for one location, grouped by category.

Get location media

get/api/v1/media
media:read
Query parameters
locationIdstringrequired
The location to look up. Required.
Response
dataobjectoptional
locationIdstringoptional
The location this media belongs to.
logoUrlstringoptional
URL of the location's logo, or null.
mediaByCategoryobjectoptional
Media items grouped by category (e.g. EXTERIOR, INTERIOR, FOOD_AND_DRINK, LOGO, TEAMS). Each item has a url, and optionally a label, kind (PHOTO or VIDEO), source, starred flag, and asset key.
photosSummaryobjectoptional
Aggregate photo counts.
totalnumberoptional
Total number of photos, or null.
byCategoryarray of objectoptional
Photo count per category.
categorystringoptional
countnumberoptional
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/media
Your API key
locationId *
{
  "data": {
    "locationId": "loc_456",
    "logoUrl": "https://cdn.synup.com/logos/loc_456.png",
    "mediaByCategory": {
      "EXTERIOR": [
        {
          "url": "https://cdn.synup.com/media/1.jpg",
          "kind": "PHOTO",
          "source": "user_upload",
          "starred": true
        }
      ]
    },
    "photosSummary": {
      "total": 12,
      "byCategory": [
        {
          "category": "EXTERIOR",
          "count": 4
        }
      ]
    }
  }
}
v1Resources/Media/getList media categories

The fixed set of category values accepted by POST/DELETE /api/v1/locations/{id}/media (COVER, LOGO, INTERIOR, ...).

List media categories

get/api/v1/media/categories
media:read
Response
dataobjectoptional
categoriesarray of stringoptional
The category values, in enforcement order.
Errors
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
get/api/v1/media/categories
Your API key
{
  "data": {
    "categories": [
      "COVER",
      "PROFILE",
      "LOGO",
      "EXTERIOR",
      "INTERIOR",
      "PRODUCT",
      "FOOD_AND_DRINK",
      "MENU",
      "AT_WORK",
      "TEAMS",
      "ROOMS",
      "COMMON_AREA",
      "ADDITIONAL"
    ]
  }
}
v1Resources/Media/patchUpdate an asset

Updates an asset's overlay metadata — tags, folder membership, assigned locations — and, for uploads only, its title. Synced/generated sources ignore title; it's read-only there.

Update an asset

patch/api/v1/media/{id}
media:write
Query parameters
idstringrequired
The asset to update.
Request body
titlestringoptional
New title. Uploads only; ignored for other sources.
tagsarray of stringoptional
Replace the asset's full tag list, by name.
folderIdsarray of stringoptional
Replace the asset's folder membership.
locationIdsarray of stringoptional
Replace the asset's assigned locations.
statusstring (ok | needs_review | spam)optional
Sets the moderation verdict by hand. Synced media only.
statusReasonstringoptional
Optional note explaining the status, shown alongside it.
Response
dataobjectoptional
assetobjectoptional
keystringoptional
Composite identifier for the asset, formatted as "<source>:<id>".
sourcestringoptional
Where this asset originated (e.g. an OS upload vs. an imported source).
idstringoptional
The asset's id within its source.
titlestringoptional
The asset's title.
filenamestringoptional
The asset's original filename.
mimestringoptional
The asset's MIME type.
kindstringoptional
The asset's kind (photo or video).
sizeBytesnumberoptional
File size in bytes, or null when unknown.
urlstringoptional
Ready-to-use URL for the asset's bytes.
thumbnailUrlstringoptional
URL of a thumbnail preview, or null.
tagsarray of stringoptional
Tags attached to the asset.
folderIdsarray of stringoptional
Asset folders this asset belongs to.
locationIdsarray of stringoptional
Every location this asset is associated with.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
429Too many requests. Retry after the number of seconds in the Retry-After header.
patch/api/v1/media/{id}
Your API key
id *
Request body
{
  "data": {
    "asset": {
      "key": "upload:abc123",
      "source": "upload",
      "id": "abc123",
      "title": "Storefront photo",
      "filename": "storefront.jpg",
      "mime": "image/jpeg",
      "kind": "image",
      "sizeBytes": 482913,
      "url": "https://cdn.synup.com/media/abc123.jpg",
      "thumbnailUrl": "https://cdn.synup.com/media/abc123-thumb.jpg",
      "tags": [
        "VIP"
      ],
      "folderIds": [
        "folder_1"
      ],
      "locationIds": [
        "loc_456"
      ]
    }
  }
}
v1Resources/Media/deleteArchive a media asset

Archives one uploaded photo/file from the Asset library — this API never permanently deletes it. The bytes, record, tag/folder memberships, and share links all stay in place; it just stops appearing anywhere in the library. Only uploads can be archived this way.

Archive a media asset

delete/api/v1/media/{id}
media:write
Query parameters
idstringrequired
The asset's key, percent-encoded (e.g. upload%3Aabc123).
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
409This asset's source is read-only (Sydekick-generated or synced media) and can't be archived here.
429Too many requests. Retry after the number of seconds in the Retry-After header.
delete/api/v1/media/{id}
Your API key
id *
{}
v1Resources/Media/postAI-edit an asset

Regenerates a Sydekick-generated asset's image (or text) in place from a text prompt — the same "Edit with AI" action available in the Data tab. Sydekick-generated assets only; uploads and synced media return a 409. Runs a background job that can take a minute or more on a cold start.

AI-edit an asset

post/api/v1/media/{id}/edit
media:write
Query parameters
idstringrequired
The generated asset to edit, percent-encoded (e.g. generated%3Aabc123).
Request body
promptstringrequired
What to change, in plain language.
Response
dataobjectoptional
assetobjectoptional
keystringoptional
Composite identifier for the asset, formatted as "<source>:<id>".
sourcestringoptional
Where this asset originated (e.g. an OS upload vs. an imported source).
idstringoptional
The asset's id within its source.
titlestringoptional
The asset's title.
filenamestringoptional
The asset's original filename.
mimestringoptional
The asset's MIME type.
kindstringoptional
The asset's kind (photo or video).
sizeBytesnumberoptional
File size in bytes, or null when unknown.
urlstringoptional
Ready-to-use URL for the asset's bytes.
thumbnailUrlstringoptional
URL of a thumbnail preview, or null.
tagsarray of stringoptional
Tags attached to the asset.
folderIdsarray of stringoptional
Asset folders this asset belongs to.
locationIdsarray of stringoptional
Every location this asset is associated with.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
404The resource wasn't found, or doesn't belong to your agency.
409Only Sydekick-generated assets can be AI-edited.
422The request is missing a required parameter or is otherwise malformed.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/media/{id}/edit
Your API key
id *
Request body*
{
  "data": {
    "asset": {
      "key": "upload:def456",
      "source": "upload",
      "id": "def456",
      "title": "Storefront photo (edited)",
      "filename": "storefront-edited.jpg",
      "mime": "image/jpeg",
      "kind": "image",
      "sizeBytes": 511204,
      "url": "https://cdn.synup.com/media/def456.jpg",
      "thumbnailUrl": "https://cdn.synup.com/media/def456-thumb.jpg",
      "tags": [
        "VIP"
      ],
      "folderIds": [
        "folder_1"
      ],
      "locationIds": [
        "loc_456"
      ]
    }
  }
}
v1Resources/Media/postUpload a media asset

Adds a new photo or video to the agency's media library from a URL or base64-encoded payload, optionally scoped to an account, client, location, or brand.

Upload a media asset

post/api/v1/media/upload
media:write
Request body
urlstringoptional
A publicly reachable URL to fetch the asset from. Provide this or base64, not both.
base64stringoptional
The raw file contents, base64-encoded. Provide this or url, not both.
mimestringoptional
MIME type of the file, e.g. image/jpeg. Inferred when omitted.
filenamestringoptional
Original filename, used for display.
titlestringoptional
A human-readable title for the asset.
scopeTypestring (account | client | location | brand)optional
What this asset belongs to: account (agency-wide), client, location, or brand.
scopeIdstringoptional
The client or location id the asset is scoped to, when scopeType is client or location.
folderIdstringoptional
An existing asset folder to file this upload into.
tagsarray of stringoptional
Free-form tags to attach to the asset.
locationIdsarray of stringoptional
Additional locations to associate this asset with, beyond scopeId.
Response
dataobjectoptional
assetobjectoptional
keystringoptional
Composite identifier for the asset, formatted as "<source>:<id>".
sourcestringoptional
Where this asset originated (e.g. an OS upload vs. an imported source).
idstringoptional
The asset's id within its source.
titlestringoptional
The asset's title.
filenamestringoptional
The asset's original filename.
mimestringoptional
The asset's MIME type.
kindstringoptional
The asset's kind (photo or video).
sizeBytesnumberoptional
File size in bytes, or null when unknown.
urlstringoptional
Ready-to-use URL for the asset's bytes.
thumbnailUrlstringoptional
URL of a thumbnail preview, or null.
tagsarray of stringoptional
Tags attached to the asset.
folderIdsarray of stringoptional
Asset folders this asset belongs to.
locationIdsarray of stringoptional
Every location this asset is associated with.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
422The request is missing a required parameter or is otherwise malformed.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/media/upload
Your API key
Request body
{
  "data": {
    "asset": {
      "key": "upload:ghi789",
      "source": "upload",
      "id": "ghi789",
      "title": "New storefront photo",
      "filename": "new-storefront.jpg",
      "mime": "image/jpeg",
      "kind": "image",
      "sizeBytes": 398211,
      "url": "https://cdn.synup.com/media/ghi789.jpg",
      "thumbnailUrl": "https://cdn.synup.com/media/ghi789-thumb.jpg",
      "tags": [],
      "folderIds": [],
      "locationIds": []
    }
  }
}
v1Resources/Media/postShare an asset

Issues (or rotates) a public link for the asset. Rotating revokes any link issued before it.

Share an asset

post/api/v1/media/{id}/share
media:write
Query parameters
idstringrequired
The asset to share.
Response
dataobjectoptional
urlstringoptional
The public share URL.
accessstring (link)optional
Always "link" on success.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
post/api/v1/media/{id}/share
Your API key
id *
{
  "data": {
    "url": "https://synup.com/s/kL9mN2pQr",
    "access": "link"
  }
}
v1Resources/Media/deleteUnshare an asset

Revokes the asset's public link.

Unshare an asset

delete/api/v1/media/{id}/share
media:write
Query parameters
idstringrequired
The asset to unshare.
Response
dataobjectoptional
accessstring (restricted)optional
Always "restricted" on success.
Errors
400The request is missing a required parameter or is otherwise malformed.
401Missing, invalid, expired, or revoked API key.
403The key lacks the required scope, or isn't authorized for this client/location.
429Too many requests. Retry after the number of seconds in the Retry-After header.
delete/api/v1/media/{id}/share
Your API key
id *
{
  "data": {
    "access": "restricted"
  }
}