Projects API

Projects are owner-private intelligence workspaces. API requests derive the user and workspace from the bearer key; callers cannot select another workspace in the request body.

Scopes

Both scopes require a workspace-bound API key. New API keys are available on Pro and Elite, even though Projects are also available in the Lite application.

Create a Project

curl -sS "https://api.y2.dev/api/v1/projects" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: project-supply-chain-2026-07" \
  -d '{
    "name": "Supply chain watch",
    "objective": "Track disruptions affecting critical suppliers",
    "instructions": "Prefer primary sources and call out conflicting evidence."
  }'

The response returns a stable prj_... ID, Location, and ETag. Reusing an Idempotency-Key with the same canonical JSON body returns the original Project.

Read and update

curl -sS "https://api.y2.dev/api/v1/projects?status=active&limit=20" \
  -H "Authorization: Bearer $Y2_API_KEY"

Project collections use the same opaque nextCursor and links.next pagination contract as other Y2 collections. Send the returned cursor unchanged to retrieve older Projects.

Use PATCH /api/v1/projects/{projectId} for metadata, view defaults, pinning, and reversible lifecycle changes. Send the latest ETag in If-Match when coordinating multiple writers.

curl -sS -X PATCH "https://api.y2.dev/api/v1/projects/$PROJECT_ID" \
  -H "Authorization: Bearer $Y2_API_KEY" \
  -H "Content-Type: application/json" \
  -H "If-Match: $PROJECT_ETAG" \
  -d '{"status":"archived"}'

Archiving keeps Project data and pauses active Automations bound to that Project. Restore it with {"status":"active"}.