Collaborate

Workspaces, members, and invitations. Integrators call https://public-api.athenous.io with X-Api-Key. The app calls https://api.athenous.io with the signed-in session. Paths start at /api/v1/collaborate.

Authentication

Send X-Api-Key: ath_… on the public host. The key needs api (or the legacy default scope) and a Pro, Agency, or Enterprise plan. A key limited to Posts or Ads can still call Collaborate. The account email on the key is the caller. Member userId values are that email.

The app host accepts Authorization: Bearer or the athenous_token cookie, and requires Origin: https://app.athenous.io. The bearer token is the JWT from POST /api/v1/auth/cli/token when the key includes cli.

curl -sS "https://public-api.athenous.io/api/v1/collaborate/workspaces" \
  -H "X-Api-Key: $ATHENOUS_API_KEY"

Seats and roles

The owner counts as a seat. Each pending invitation counts too. The cap follows the workspace owner's plan.

Plan	Seats
`free`, `starter`	1
`pro`	3
`agency`	5
`enterprise`	Unlimited

Role	What it can do
`OWNER`	Everything an admin can do, plus delete the workspace and transfer ownership. Assigned only by creating the workspace or by transfer.
`ADMIN`	Update the workspace, add and remove members, change roles, invite, cancel, and resend.
`MEMBER`	Read the workspace, its members, and its pending invitations. Default role on an invite.
`VIEWER`	Same read access as a member. Cannot manage people or edit the workspace.

Workspaces

Method	Path	Who	Result
POST	`/api/v1/collaborate/workspaces`	Any signed-in account	201. You become `OWNER`. Body `name` (1–255) and optional `description`.
GET	`/api/v1/collaborate/workspaces`	Any signed-in account	Array of workspaces you own or belong to.
GET	`/api/v1/collaborate/workspaces/{id}`	Member	One workspace.
PUT	`/api/v1/collaborate/workspaces/{id}`	Owner or admin	Update `name` and `description`.
DELETE	`/api/v1/collaborate/workspaces/{id}`	Owner	`{"deleted": true}`.
POST	`/api/v1/collaborate/workspaces/{id}/transfer-ownership`	Owner	Body `newOwnerUserId` (must already be a member) and optional `previousOwnerNewRole`. That role defaults to `ADMIN` and cannot be `OWNER`.

curl -sS -X POST "https://public-api.athenous.io/api/v1/collaborate/workspaces" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Client North","description":"Organic and paid for this client"}'

Members

Method	Path	Who	Result
GET	`/api/v1/collaborate/workspaces/{id}/members`	Member	Array of members.
POST	`/api/v1/collaborate/workspaces/{id}/members`	Owner or admin	201. Body `userId` (account email) and optional `role` (`ADMIN`, `MEMBER`, or `VIEWER`). Counts toward the seat cap.
PATCH	`/api/v1/collaborate/workspaces/{id}/members/{memberUserId}/role`	Owner or admin	Body `{"role":"ADMIN"}`. Cannot change the owner, and cannot assign `OWNER`.
DELETE	`/api/v1/collaborate/workspaces/{id}/members/{memberUserId}`	Owner or admin, or yourself	`{"deleted": true}`. The owner cannot be removed. Sending your own id leaves the workspace.

Invitations

An invitation is pending for 7 days. Resend sets a new 7-day expiry. An expired invitation has to be cancelled and created again. emailSent is present on create and resend. It is true when Athenous delivered the mail.

Method	Path	Who	Result
GET	`/api/v1/collaborate/workspaces/{id}/invitations`	Member	Pending invitations for this workspace.
POST	`/api/v1/collaborate/workspaces/{id}/invitations`	Owner or admin	201. Body `email` and optional `role`. `OWNER` is stored as `MEMBER`. A pending invite for that email is rejected. Counts toward the seat cap.
DELETE	`/api/v1/collaborate/workspaces/{id}/invitations/{invitationId}`	Owner or admin	Cancel a pending invitation. `{"deleted": true}`.
POST	`/api/v1/collaborate/workspaces/{id}/invitations/{invitationId}/resend`	Owner or admin	Pending invitations only. Extends `expiresAt` by 7 days.
GET	`/api/v1/collaborate/invitations`	The invitee	Pending invitations for the signed-in email.
POST	`/api/v1/collaborate/invitations/{id}/accept`	The invitee	Join the workspace. The pending invite already counted as a seat.
POST	`/api/v1/collaborate/invitations/{id}/decline`	The invitee	Mark the invitation declined.

curl -sS -X POST "https://public-api.athenous.io/api/v1/collaborate/workspaces/$WORKSPACE_ID/invitations" \
  -H "X-Api-Key: $ATHENOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email":"sam@example.com","role":"MEMBER"}'

Fields

Workspace

Field	Type	Description
`id`	UUID	Workspace id.
`ownerId`	string	Account email of the owner.
`name`	string	1 to 255 characters.
`description`	string	Empty string when none was stored.
`createdAt`	string	ISO-8601 UTC.
`updatedAt`	string	ISO-8601 UTC.
`currentUserRole`	string or null	`OWNER`, `ADMIN`, `MEMBER`, or `VIEWER`.
`memberId`	UUID or null	Your membership row.

Member

Field	Type	Description
`id`	UUID	Membership id.
`workspaceId`	UUID	Workspace this membership belongs to.
`userId`	string	Account email.
`role`	string	`OWNER`, `ADMIN`, `MEMBER`, or `VIEWER`.
`joinedAt`	string	When this person joined.

Invitation

Field	Type	Description
`id`	UUID	Invitation id.
`workspaceId`	UUID	Workspace being joined.
`email`	string	Invitee email.
`role`	string	Role they will receive on accept.
`invitedByUserId`	string	Email of the person who sent it.
`status`	string	`PENDING`, `ACCEPTED`, `DECLINED`, `EXPIRED`, or `CANCELLED`.
`createdAt`	string	When it was created.
`expiresAt`	string	When a pending invitation stops being acceptable.
`respondedAt`	string or null	When it was accepted, declined, or expired.
`emailSent`	boolean	Present on create and resend only.

Errors

A missing or invalid key or token returns 401. A key without api, or a plan below Pro, returns 403. The public host allows 100 requests per minute per key, or 500 when the key includes batch. A call to api.athenous.io without Origin: https://app.athenous.io returns 403 with {"detail":"Origin not allowed"}.

Validation and rule failures return 400. Unknown ids return 404. Those bodies use timestamp, status, error, message, and path. A body that fails field checks also includes errors[] with field and message.

{
  "timestamp": "2026-10-30T10:00:00Z",
  "status": 400,
  "error": "Bad Request",
  "message": "Team seat limit reached (3 / 3). Remove a member or revoke a pending invite.",
  "path": "/api/v1/collaborate/workspaces/WORKSPACE_ID/invitations"
}