Collaborators

A collaborator is a writer, publisher, or master owner in your rights directory — the people and entities referenced by split sheets and works. Collaborators are owner‑scoped: ownerId always comes from the authenticated actor, never from the request body, and is redacted from every response.

Every endpoint is under /api/swayzio/v1 and requires a Clerk actor. Responses strip ownerId via the clientCollaborator* DTOs — see Data Contracts. Runtime is native→proxy except where noted below.

Endpoints

Method	Path	Purpose	Auth	Request	Response
`GET`	`/v1/collaborators`	List collaborators	Clerk actor	`?limit` `?query` `?role`	`{ records: Collaborator[] }`
`POST`	`/v1/collaborators`	Create a collaborator	Clerk actor	`createCollaboratorRequestSchema`	`Collaborator` `201`
`PATCH`	`/v1/collaborators/:collaboratorId`	Update	Clerk actor	`updateCollaboratorRequestSchema`	`Collaborator`
`GET`	`/v1/collaborators/summary`	Directory rollups	Clerk actor	`?view` `?limit` `?query`	`{ records: CollaboratorSummary[] }`

createCollaboratorRequestSchema:

name — required, trimmed
email? — valid email
pro? — performing‑rights org (free‑text)
ipiNumber? — IPI number
entityType? — person | company
roles — array of writer | publisher | master_owner (defaults to [])

updateCollaboratorRequestSchema requires ≥1 field; email, pro, and ipiNumber accept null to clear.

The summary endpoint takes view ∈ songwriters | publishers (default songwriters), plus limit (1..100, default 50) and query. Each CollaboratorSummary extends the collaborator with collaborationCount and an array of works (trackId, title, artist, entryType, percentage).

Proxy‑only (Fastify Core API)

Method	Path	Purpose	Auth	Request	Response
`GET`	`/v1/collaborators/:collaboratorId/works`	A collaborator’s works	Clerk actor	`?view` `?limit`	`{ records: CollaboratorWork[] }`
`DELETE`	`/v1/collaborators/:collaboratorId`	Delete a collaborator	Clerk actor	—	`204`

⚠️

These two routes are implemented in the Fastify Core API only — they are not served natively, so they always run via the proxy path. The dedicated …/works endpoint above is distinct from the works array already embedded in each GET /v1/collaborators/summary record.

`POST /v1/collaborators`

Creates a directory entry. ownerId is taken from the actor — never the body.

curl -s -X POST https://app.swayzio.com/api/swayzio/v1/collaborators \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Jane Writer",
        "email": "jane@example.com",
        "pro": "ASCAP",
        "entityType": "person",
        "roles": ["writer"]
      }'

Returns the created Collaborator (201) with ownerId stripped.

`GET /v1/collaborators`

Lists the directory, filterable by free‑text query and role.

curl -s "https://app.swayzio.com/api/swayzio/v1/collaborators?role=publisher&limit=25" \
  -H "Authorization: Bearer $TOKEN"

`GET /v1/collaborators/summary`

Directory rollups for the songwriter or publisher view, each with its collaborationCount and embedded works.

curl -s "https://app.swayzio.com/api/swayzio/v1/collaborators/summary?view=songwriters" \
  -H "Authorization: Bearer $TOKEN"

See Conventions for the error envelope and response headers, and Data Contracts for the redaction pattern.

Libraries Billing