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 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

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

{
  "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

{
  "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.

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:

{
  "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.