REST Conventions

The public API is organized around resources. Routes should name objects, not UI modules or button actions.

Resource naming

Use plural nouns:


/candidates
/jobs
/clients
/applications
/interviews
/inbox-items
/agent-tasks

Avoid route names tied to product screens:


/ats/candidates
/crm/clients
/find-clients

CRM and ATS are workflow surfaces in the app. They should be represented as filters or query context, not separate entities.


GET /candidates?surface=crm
GET /candidates?surface=ats

Standard methods

Method	Use
`GET /resources`	List resources
`POST /resources`	Create a resource
`GET /resources/:id`	Read one resource
`PATCH /resources/:id`	Update part of a resource
`PUT /resources/:id`	Replace a resource or owned collection
`DELETE /resources/:id`	Delete or archive a resource

Relationships

Prefer nested routes when the child cannot stand alone:


GET /clients/:id/contacts
POST /clients/:id/contacts
DELETE /clients/:id/contacts/:contactId

Use top-level resources when the entity has its own lifecycle:


GET /applications?candidateId=...&jobId=...
POST /applications
PATCH /applications/:id

Workflow commands

Some recruiting actions are commands rather than simple CRUD. Model those as resources where possible.

Preferred:


PATCH /applications/:id
POST /applications/:id/stage-transitions
POST /application-presentations
DELETE /application-presentations/:id
POST /agent-tasks
PATCH /inbox-items/:id
PATCH /notifications/:id
PATCH /notifications

Avoid:


POST /applications/:id/set-stage
POST /applications/:id/advance-stage
POST /applications/:id/unpresent
PATCH /notifications/read/:id
PATCH /notifications/read-all
POST /inbox/:id/actions/create-client
POST /inbox/:id/actions/refine-search

Legacy command routes may remain temporarily, but frontend clients should move to the canonical resource routes as they are added.

Versioning

The version is part of the path:


https://api.vitae.ai/v1

Breaking changes require a new version or a compatibility alias. The frontend and API route changes ship together in the same implementation pass.