---
title: "Create embedded URL"
method: POST
path: "/api/v1/annotations/{annotationID}/create_embedded_url"
tags: ["Annotation"]
---

# Create embedded URL

`POST /api/v1/annotations/{annotationID}/create_embedded_url`

Similar to [start embedded annotation](/api/annotation#start-validation-for-embedded-use) endpoint but can be
called for annotations with all statuses and does not switch status.

Embedded annotation cannot be started by users with admin or organization group admin roles. We strongly recommend
creating embedded URLs by users with `annotator_embedded` [user role](/api/user-role) and permissions for the given
queue only to limit the scope of actions that user is able to perform to required minimum.

## Path parameters

- `annotationID` integer, required

## Request body

- object
  - `return_url` string, uri — URL to redirect to after annotation is confirmed
  - `cancel_url` string, uri — URL to redirect to when annotation is cancelled
  - `delete_url` string, uri — URL to redirect to when annotation is deleted
  - `postpone_url` string, uri — URL to redirect to when annotation is postponed
  - `max_token_lifetime_s` number, float — Duration (in seconds) for which the token will be valid. The default is the [queue's](/api/queue) `session_timeout`).

## Response `200`

Embedded URL created successfully

- object
  - `url` string, uri — URL to be used in the browser iframe/popup window. URL includes a token that is valid for this document only for a limited period of time.
  - `status` string — Status of annotation, see [annotation lifecycle](/guides/annotation-lifecycle).

## Other responses

- `400` — Invalid input data.
- `401` — The username/password is invalid or token is invalid (e.g. expired).
- `403` — Insufficient permission, missing authentication, invalid CSRF token and similar issue.
- `404` — The specified resource was not found.
- `413` — Payload too large (especially for files uploaded).
- `429` — Request rate is too high, wait before sending more requests. See [Rate Limiting](/guides/overview#rate-limiting) for more details.
- `500` — Server failure while processing the request.
- `502` — Invalid response from the upstream server.
- `503` — We're temporarily offline for maintenance. Please try again later.
- `504` — Upstream server could not complete the request in time.

---

[API](https://skmtc.dev/rossum/apis/rossum-api.md) · [All operations](https://skmtc.dev/rossum/apis/rossum-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rossum/rossum-api/revisions/f1b5a910991d/schema)