UrbanLoop API guide

Connect your application to UrbanLoop to browse signage content, check screen assignments and review updates before applying them.

Get API access

The HTTPS API base is https://api.urbanloop.ai/agent/v1. Your application needs an UrbanLoop-registered OAuth client. Contact UrbanLoop about registering an integration. Include your application name, HTTPS callback URL and what you want it to do.

An UrbanLoop organization administrator or curator signs in and approves access for their organization. Each request is limited by the granted scopes and that user’s current role and site access. Self-serve API keys and OAuth client registration are currently unavailable.

Authorize your application

  1. Use the authorization endpoint listed in OAuth discovery. Send your registered client_id and exact redirect_uri with response_type=code, a fresh state, the requested scope, and your PKCE code_challenge with code_challenge_method=S256.
  2. Set the OAuth resource to https://api.urbanloop.ai/agent/mcp for authorization, token exchange and refresh. It identifies the token’s audience. Send JSON API requests to the /agent/v1 base.
  3. After the user approves the connection, verify the returned state. Exchange the code at the token endpoint using a form-encoded request with grant_type=authorization_code, client_id, code, code_verifier, redirect_uri and resource. Use public-client authentication with no client secret.
  4. Send the access token in the Authorization: Bearer header. Access tokens expire after 15 minutes. Refresh with grant_type=refresh_token, client_id, the latest refresh_token and resource. Serialize refreshes and replace the stored token pair after each refresh. Reusing a retired refresh token can revoke the connection.

Request screens:read to list TVs and library:read to browse slides and playlists. Add write scopes only for the actions your app offers. Some operations require multiple scopes and organization admin permission.

Make your first request

With a valid access token in URBANLOOP_ACCESS_TOKEN, list the TVs the user can access.

curl --fail-with-body \
  --header "Authorization: Bearer $URBANLOOP_ACCESS_TOKEN" \
  'https://api.urbanloop.ai/agent/v1/screens'

The response contains screens and next_cursor. Pass a non-null next_cursor back as the cursor query parameter for the next page. Use the returned IDs for subsequent requests because names can repeat.

Use a read-only search to find slides named Welcome.

curl --fail-with-body \
  --header "Authorization: Bearer $URBANLOOP_ACCESS_TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{"kind":"slides","query":"Welcome"}' \
  'https://api.urbanloop.ai/agent/v1/library/search'

Use kind: "playlists" for playlists and pass next_cursor as cursor in the JSON body to continue a search.

Common operations

The paths below are relative to /agent/v1.

Read signage data
OperationMethod and path
List TVs or inspect one TV’s ordered assignmentsGET /screens
GET /screens/{id}
Search and inspect slides or playlistsPOST /library/search
GET /library/slides/{id}
GET /library/playlists/{id}
Browse saved files and view retained history where authorizedGET /library/assets
GET /library/assets/{id}/history
Read schedule windowsPOST /calendar
Inspect TV settings and groupsGET /screens/{id}/settings
GET /screen-groups
GET /screen-groups/{id}

For POST /calendar, send kind as slide, playlist or screen, along with target_id, from_date and to_date in YYYY-MM-DD format. The date range can span up to 42 calendar days inclusive. Schedule windows use local TV time.

Retained originals and file history require library:read, content:read, organization admin access and consent that covers file history.

Review and apply changes

  • Upload a file. Create an upload with POST /asset-drafts and send title, mime_type and size_bytes. Transfer the raw file with PUT to the returned upload_url using its exact upload_headers. Use the draft ID to check readiness with GET /asset-drafts/{id} and request review with POST /asset-drafts/{id}/review. Save the approved file with POST /library/edits/{id}/apply using the review ID.
  • Assign an existing playlist. Send kind: "playlist", source_id, screen_ids and an explicit mode: "append_assignment" to POST /publications/preview-existing to keep the TVs’ existing playlists. Show the proposed assignments to the user, then apply the approved review with POST /publications/{id}/publish.
  • Edit shared content or settings. Use POST /library/edits/preview for supported library edits and POST /screen-settings/preview for TV settings. Show the affected items and TVs before applying with POST /library/edits/{id}/apply or POST /screen-settings/{id}/apply. Shared edits can affect every TV using that content.

Send an Idempotency-Key on creation and preview requests that require it. Use a fresh key for a new operation and the same key and payload when retrying that operation. If an apply response is unclear, check the status with GET /publications/{id}, GET /library/edits/{id} or GET /screen-settings/{id} before retrying. Review per-TV results for group operations. To confirm playback after saving an assignment, check the TV itself.

Troubleshooting

  • 401 Check the access token. Refresh it or ask the user to reconnect if the grant is no longer valid.
  • 403 Check the granted scopes and the user’s current role and site access.
  • 404 Check the ID and whether that record is visible to the signed-in user.
  • 409 Read the error and the latest operation status. If the review expired or its inputs changed, refresh the item and create a new review.
  • 429 Back off and retry later.

Keep tokens and temporary file links out of logs. To end access, use the connection’s revocation endpoint or disconnect the application in UrbanLoop. Saved changes remain in UrbanLoop.

Contact UrbanLoop support · Privacy policy