---
title: "Create an agent browser session for a project"
method: POST
path: "/projects/{projectId}/agent-session"
tags: ["Projects"]
---

# Create an agent browser session for a project

`POST /projects/{projectId}/agent-session`

## Request

- Base URL: `https://app.flora.ai/api/v1`
- URL: `https://app.flora.ai/api/v1/projects/{projectId}/agent-session`
- Auth: HTTP bearer

Mints a one-shot sign-in link for an agent that has its own browser (for example Claude Code Desktop or Cowork with WebMCP). Opening the link signs the agent in as the credential's user and lands on the project canvas with FLORA's in-page WebMCP tools enabled, so the agent can drive the canvas directly. The link is consumed on first visit and the session it grants lasts `session_hours` (1–24, default 8) and acts as the user — treat it as a secret. The session acts as the whole user, so only OAuth credentials and API keys created before per-workspace permissions existed may create one; keys that carry a permission map are refused with `403 forbidden`.

## Path parameters

- `projectId` string, required: Project identifier

## Request body

- object
  - `session_hours` integer: How long the browser session minted by the link lasts, in hours (1–24, default 8).

## Response `201`

Agent session link created.

- object
  - `project_id` string, required: Project identifier
  - `workspace_id` string, required: Workspace identifier
  - `url` string, uri, required: One-shot sign-in link. Opening it in a browser signs the agent in as the credential's user and lands on the project canvas with WebMCP enabled. It is consumed on first visit; navigate within the tab rather than reloading it.
  - `canvas_url` string, uri, required: Project canvas URL
  - `expires_at` string, date-time, required: When the browser session minted by the link expires
  - `session_hours` integer, required: Session length the link grants

## Other responses

- `400`: 400
- `401`: 401
- `402`: 402
- `403`: 403
- `404`: 404
- `409`: 409
- `429`: 429
- `500`: 500
- `503`: 503

## Changes

- **2026-10-28** `a8351619f225`: 9 warning
  - added the new `not_configured` enum value to the `error/code` response property for the response status `400`
  - added the new `not_configured` enum value to the `error/code` response property for the response status `401`
  - added the new `not_configured` enum value to the `error/code` response property for the response status `402`
  - added the new `not_configured` enum value to the `error/code` response property for the response status `403`
  - …5 more
- **2026-10-16** `e54130373b10`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/florafauna-ai/apis/flora-ai-api/changes/projects/:projectId/agent-session/post.md)

---

[API](https://skmtc.dev/florafauna-ai/apis/flora-ai-api.md) - [All operations](https://skmtc.dev/florafauna-ai/apis/flora-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/florafauna-ai/apis/flora-ai-api/revisions/87cfe2c4ac29?raw)