---
title: "Create embedded editor session"
method: POST
path: "/v2/organizations/{organizationId}/templates/{externalId}/embed-sessions"
tags: ["Embedded editor"]
---

# Create embedded editor session

`POST /v2/organizations/{organizationId}/templates/{externalId}/embed-sessions`

## Request

- Base URL: `https://api.pdfs.build`
- URL: `https://api.pdfs.build/v2/organizations/{organizationId}/templates/{externalId}/embed-sessions`
- Auth: HTTP bearer

Called from your backend. Exchanges the API key for a short-lived session token (`emb_...`) scoped to one template and one of your end users; your frontend mounts the editor with that token. Every AI turn in the session is metered against `externalTenantId`. Requires the Platform (or a custom) plan.

## Request body

- EmbedSessionRequest
  - `externalTenantId` string, required: Your customer's id. AI usage in the session is metered against it.
  - `externalUserId` string, required: The end user's id in your system, for attribution.
  - `expiresInSeconds` integer: Session lifetime.

## Response `201`

The session token. Hand `token` to the browser; never the API key.

- EmbedSession
  - `sessionId` string, required
  - `token` string, required: Session token (`emb_...`) for `@pdfsbuild/react`. Scoped to this template and user.
  - `templateId` string, required: The template's internal id — what the SDK addresses the document by.
  - `expiresAt` string, date-time, required

## Other responses

- `400`: Invalid request body; `issues` describes each field.
- `401`: Missing, invalid or expired API key.
- `403`: `embedded_plan_required` or `organization_scope_mismatch`.
- `404`: The template is not accessible to this key.
- `502`: The service that owns this resource could not be reached. Safe to retry.

---

[API](https://skmtc.dev/pdfs/apis/pdfs-build-api.md) · [All operations](https://skmtc.dev/pdfs/apis/pdfs-build-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pdfs/apis/pdfs-build-api/revisions/1c7340b9521d?raw)