---
title: "Projects API"
description: "Create, list, inspect, update, archive, and restore owner-private Projects through the Y2 API."
canonical: https://y2.dev/docs/api/projects/
---

# Projects API

Create, list, inspect, update, archive, and restore owner-private Projects through the Y2 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

| Operation                                         | Scope            |
| ------------------------------------------------- | ---------------- |
| List or get Projects                              | `projects:read`  |
| Create, update, archive, restore, or pin Projects | `projects:write` |

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"}`.

[Generated Projects reference](https://y2.dev/docs/api/reference/projects): Exact paths, parameters, request bodies, responses, and schemas

[Projects product guide](https://y2.dev/docs/projects): App views, private knowledge, evidence, resources, and lifecycle behavior