Start without an account
Spin up a Raster library, upload images, and get a working CDN URL with one call — no signup, no key up front. The user claims the library later from an emailed link.
An AI agent can give someone a working, organized image library before they ever create a Raster account. One call mints a new organization, a starter library, and a ready-to-use API key from just an email address. The agent uploads and organizes right away; the person receives a link to claim the library into a real account when they want to keep it.
This is the fastest path from "a user asked me to handle some images" to "here is your CDN-hosted, tagged library."
The flow at a glance
Create
One call with the user's email returns an organizationId, a libraryId, an
apiKey, and a claimUrl. No account, no key needed beforehand.
Work
Use the returned key as a normal Bearer token to upload, tag, search, and describe assets. Every standard tool and endpoint works against the new library.
Hand off
Give the user the claimUrl (it is also emailed). They open it, sign in, and
the library — with everything in it — becomes theirs on a real account.
Create the library
The canonical definition, with the full parameter and response tables, lives at
POST /libraries and the
create_organization MCP tool. Pick the
transport your client uses.
create_organization needs no Bearer key — it mints one. Call it with the
user's email:
{
"name": "create_organization",
"arguments": { "email": "user@example.com", "name": "Q3 campaign" }
}It returns the organizationId, libraryId, apiKey, and claimUrl. Use that
apiKey as the Bearer token for every following tool call.
POST to https://api.raster.app/libraries with no Authorization header — the
endpoint mints the key:
curl --request POST \
--header 'Api-Version: 2026-05-20' \
--header 'Content-Type: application/json' \
--url 'https://api.raster.app/libraries' \
--data '{"email":"user@example.com","name":"Q3 campaign"}'The { data } envelope carries the organizationId, libraryId, apiKey, and
claimUrl.
Drive the MCP server from the Responses API's remote mcp tool. The
create_organization tool is callable before you hold a key, so the first call
needs no authorization:
from openai import OpenAI
client = OpenAI()
resp = client.responses.create(
model="gpt-5.5",
tools=[{
"type": "mcp",
"server_label": "raster",
"server_url": "https://mcp.raster.app/",
}],
input="Create a Raster library for user@example.com and tell me the claim link.",
)Pass the returned apiKey as the authorization Bearer token on later calls so
the agent can upload to the library it just made.
The apiKey is returned once and stored only in encrypted form afterward.
Persist it the moment you receive it — you cannot read it back until the user
claims the library and reveals it from settings.
Upload and organize
The returned apiKey, organizationId, and libraryId are everything the
standard asset surface needs. Tag and describe what you add so the library is
useful the moment the user opens it. The full loop is in
Using Raster from an AI agent.
Over REST, upload is a multipart/form-data request with a files field — see
POST /:orgId/libraries/:libraryId/assets:
curl --request POST \
--header 'Authorization: Bearer <API_KEY>' \
--header 'Api-Version: 2026-05-20' \
--url 'https://api.raster.app/organizations/<organizationId>/libraries/<libraryId>/assets' \
--form 'files=@/path/to/photo.jpg'Over MCP, upload_asset also accepts a public
http(s) URL the server fetches for you, or inline base64 — convenient when an
agent has a link rather than a local file.
Each returned asset carries a permanent CDN url — share those links with the
user directly. Uploads process asynchronously and appear in lists and search a
few seconds later.
Hand off the claim link
The library is held for a claim window after creation — see
POST /libraries for the exact length and
the per-email cap on active unclaimed libraries. The claim link is emailed when
the address accepts mail, and is always returned as claimUrl — surface it to
the user yourself so the hand-off never depends on email delivery.
When the user opens claimUrl and signs in, the library and every asset in it
transfer to their account, and the API key you used becomes a normal key they
can manage in settings. A library left unclaimed when the window closes is
removed along with its images.
While unclaimed, a library is on a trial footing — encourage the user to claim
it to keep their work. Creating past the per-email cap returns
400 BAD_USER_INPUT.
A prompt you can reuse
Configure an agent to run this flow on its own. Each prompt is available per transport — pick your tab.
When a user without a Raster account asks you to store or organize images:
1. Call `create_organization` with their email. Save the returned `organizationId`,
`libraryId`, and `apiKey` right away — the `apiKey` is shown only once. Use that
`apiKey` as the Bearer token on every later call.
2. Upload their images with `upload_asset` or `upload_assets` — pass a public
http(s) URL when you have one, otherwise base64 — then make them findable with
`tag_assets` and `update_asset_description`.
3. Processing is asynchronous, so re-run `list_assets` a few seconds later to
confirm an upload landed. Share each asset's permanent `url` and the library URL.
4. Give the user the returned `claimUrl` and tell them to open it and sign in within
the claim window to keep this library and everything in it on a real account.
Surface the `claimUrl` yourself, since the hand-off holds even when email delivery
is uncertain.When a user without a Raster account asks you to store or organize images:
1. `POST https://api.raster.app/libraries` with their email in the body and an
`Api-Version: 2026-05-20` header, sending no `Authorization`. Read the `{ data }` envelope
and persist `organizationId`, `libraryId`, `apiKey`, and `claimUrl` immediately —
the `apiKey` is returned once. Send it as `Authorization: Bearer <API_KEY>`
alongside `Api-Version` on every later call.
2. Upload their files to
`POST /organizations/:organizationId/libraries/:libraryId/assets` as
`multipart/form-data` with a repeatable `files` field, letting the client set the
multipart `Content-Type`. List first with `GET .../assets` and dedupe by `name`
so a retry stays clean. Make them findable with `POST .../assets/tag` and
`PATCH .../assets/:assetId/description`.
3. Processing is asynchronous, so re-read `GET .../assets/:assetId` a few seconds
later to pick up the computed fields. Share each asset's permanent CDN `url` and
the library URL.
4. Give the user the returned `claimUrl` and tell them to open it and sign in within
the claim window to keep this library and everything in it on a real account.
Surface the `claimUrl` yourself, since the hand-off holds even when email delivery
is uncertain. See [`POST /libraries`](/api/rest/endpoints#post-libraries) for the
claim window and the per-email cap.When a user without a Raster account asks you to store or organize images, mint
the library first over REST or MCP, then drive the work in GraphQL with the key
it returns:
1. Create the library with the anonymous REST call
[`POST /libraries`](/api/rest/endpoints#post-libraries) (or the MCP
`create_organization` tool). Persist the returned `organizationId`, `libraryId`,
`apiKey`, and `claimUrl` immediately — the `apiKey` is returned once. Send it as
`Authorization: Bearer <API_KEY>` on every GraphQL request, POSTed to
`https://api.raster.app/`.
2. Run `viewer` once to confirm the key's `organizationId` and authorized
`libraries`. Upload with the `uploadAssets` mutation (`files`, `email`), reading
back `assets`. Query `assets` first and dedupe by `name` so a retry stays clean,
then make them findable with `tagAssets` and `updateAssetDescription`.
3. Processing is asynchronous, so re-run the `asset` query a few seconds later to
pick up the computed fields. Share each asset's permanent CDN `url` and the
library URL.
4. Give the user the `claimUrl` you saved from the create step and tell them to open
it and sign in within the claim window to keep this library and everything in it
on a real account. Surface the `claimUrl` yourself, since the hand-off holds even
when email delivery is uncertain.Clients that load agent skills can fetch Raster's published raster-api skill
from
https://raster.app/.well-known/agent-skills/index.json
to wire these tools up automatically.
For the focused prompts that cover connecting, adding, organizing, finding, and restructuring once an account exists, see Reusable prompts by use case.