# Projects & organizations

The bootstrap surface. These are the only endpoints that take an
**organization key** (`pha_…`) and no project — everything else in the
reference is project-scoped.

See [API conventions](/docs/conventions) for the base URL, error shape and
status codes.

## `GET /api/v1/organizations`

The organization behind the presented key.

**Scope:** `projects:read` · **Credential:** organization key

```bash
curl https://pharosbase.com/api/v1/organizations \
  -H "Authorization: Bearer $PHAROS_ORG_KEY"
```

```json
{
  "organizations": [
    { "id": "org_…", "slug": "acme", "name": "Acme" }
  ]
}
```

The array always holds exactly one entry — a key belongs to one organization.
It is an array so that a future credential spanning several does not change
the shape.

## `GET /api/v1/projects`

Every project the key can reach. This is how an agent discovers what slugs
exist before doing anything else.

**Scope:** `projects:read` · **Credential:** organization key

```json
{
  "projects": [
    { "id": "prj_…", "slug": "acme-app", "name": "Acme App" }
  ]
}
```

## `POST /api/v1/projects`

Create a project. The org-key bootstrap path: a project key is pinned to a
project that already exists, so it cannot create one.

**Scope:** `projects:write` · **Credential:** organization key

| Field | Type | Notes |
| --- | --- | --- |
| `name` | string | **Required.** |
| `slug` | string | Derived from `name` when omitted. Globally unique. |
| `sesFromEmail` | string | Verified sender address for this project's mail. |
| `sesFromName` | string | Display name on outgoing mail. |
| `sesRegion` | string | Sending region. |
| `colorPrimary` | string | Brand colour, baked into seeded templates. |
| `colorSecondary` | string | Brand colour, baked into seeded templates. |
| `mailingAddress` | string | Physical address in the email footer. Required by bulk-mail rules in most jurisdictions — set it before you send. |

```bash
curl -X POST https://pharosbase.com/api/v1/projects \
  -H "Authorization: Bearer $PHAROS_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme App",
    "sesFromEmail": "hi@acme.dev",
    "sesFromName": "Acme",
    "mailingAddress": "1 Example St, Lisbon, Portugal"
  }'
```

`201`:

```json
{
  "project": {
    "id": "prj_…",
    "slug": "acme-app",
    "name": "Acme App",
    "sesFromEmail": "hi@acme.dev",
    "sesFromName": "Acme",
    "sesRegion": null,
    "mailingAddress": "1 Example St, Lisbon, Portugal",
    "createdAt": "2026-08-01T14:03:00.000Z"
  },
  "defaultList": { "slug": "newsletter", "name": "Newsletter" }
}
```

A `newsletter` list is seeded so the project can accept subscribers
immediately. That slug is what `recipientMode: "list:newsletter"` refers to
when you send.

**`409`** means the slug is taken. Slugs are globally unique, not unique per
organization — pass an explicit `slug` to pick another.

> The `ses*` field names predate multi-provider sending and are kept for
> compatibility. They configure the project's sender identity whichever
> provider ends up delivering the mail.