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
- Use the authorization endpoint listed in OAuth discovery. Send your registered
client_idand exactredirect_uriwithresponse_type=code, a freshstate, the requestedscope, and your PKCEcode_challengewithcode_challenge_method=S256. - Set the OAuth
resourcetohttps://api.urbanloop.ai/agent/mcpfor authorization, token exchange and refresh. It identifies the token’s audience. Send JSON API requests to the/agent/v1base. - After the user approves the connection, verify the returned
state. Exchange the code at the token endpoint using a form-encoded request withgrant_type=authorization_code,client_id,code,code_verifier,redirect_uriandresource. Use public-client authentication with no client secret. - Send the access token in the
Authorization: Bearerheader. Access tokens expire after 15 minutes. Refresh withgrant_type=refresh_token,client_id, the latestrefresh_tokenandresource. 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.
| Operation | Method and path |
|---|---|
| List TVs or inspect one TV’s ordered assignments | GET /screensGET /screens/{id} |
| Search and inspect slides or playlists | POST /library/searchGET /library/slides/{id}GET /library/playlists/{id} |
| Browse saved files and view retained history where authorized | GET /library/assetsGET /library/assets/{id}/history |
| Read schedule windows | POST /calendar |
| Inspect TV settings and groups | GET /screens/{id}/settingsGET /screen-groupsGET /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-draftsand sendtitle,mime_typeandsize_bytes. Transfer the raw file withPUTto the returnedupload_urlusing its exactupload_headers. Use the draft ID to check readiness withGET /asset-drafts/{id}and request review withPOST /asset-drafts/{id}/review. Save the approved file withPOST /library/edits/{id}/applyusing the review ID. - Assign an existing playlist. Send
kind: "playlist",source_id,screen_idsand an explicitmode: "append_assignment"toPOST /publications/preview-existingto keep the TVs’ existing playlists. Show the proposed assignments to the user, then apply the approved review withPOST /publications/{id}/publish. - Edit shared content or settings. Use
POST /library/edits/previewfor supported library edits andPOST /screen-settings/previewfor TV settings. Show the affected items and TVs before applying withPOST /library/edits/{id}/applyorPOST /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.