Service endpoint reference

All paths on this page are relative to:

https://api.champrep.com

Use a scoped bearer credential as described in authentication and API keys. A listed route is still subject to current service availability, plan and organization settings, role permissions, resource access, and live usage controls.

Service map

Area	Prefix	Scopes
Identity and profile	/v1/auth, /v1/users	users:read and credential context
Search across services	/v1/search	The read scope of each service searched
Drive	/v1/drive	drive:read, drive:write, drive:delete
Chat	/v1/chat	chat:read, chat:write
Calendar	/v1/calendar	calendar:read, calendar:write
Contacts	/v1/contacts	contacts:read, contacts:write
Meet	/v1/meet	meet:read, meet:write
Notes	/v1/notes	notes:read, notes:write
Learn	/v1/learn, /v1/courses	courses:read, courses:write
CHAMPREP AI	/v1/ai	ai:chat
Mail	/v1/mail	mail:read, mail:write, mail:send
Work	/v1/work	work:read, work:write, work:delete
Org Chart	/v1/charts	charts:read, charts:write, charts:delete
Forms	/v1/forms	forms:read, forms:write
Invoice	/v1/invoice	invoice:read, invoice:write, invoice:send, invoice:delete
CHAMPREP QA	/v1/qa	qa:read, qa:write
CHAMPREP Business	/v1/business	business:read, business:manage
Billing	/v1/billing	billing:read, billing:manage
Webhooks	/v1/webhooks	webhooks:manage

GET, HEAD, and OPTIONS normally require the read scope. Create, update, and action methods require the write or manage scope. Delete methods require a delete scope where the service defines one. A route can require additional role or resource permissions in the destination service.

Identity and Gateway status

Method	Path	Purpose
GET	/v1/version	Return public Gateway version information.
GET	/v1/auth/whoami	Return active user, profile, credential, and plan context.
GET	/v1/auth/quota	Return the current key and Gateway quota snapshot.
GET	/v1/users/me	Return the current user’s profile.
GET	/v1/users/me/notifications	List notifications visible to the current user.

The browser-assisted CLI exchange also uses /v1/auth/cli/start, /v1/auth/cli/device, and /v1/auth/cli/poll. These routes are implemented by the official CLI; custom applications should not imitate the CLI approval protocol when an API key meets their needs.

Search across services

Method	Path	Scope	Purpose
GET	/v1/search	Per service, see below	Search every service this credential can reach, in one call.
GET	/v1/search/services	None	List which services this credential is able to search.

/v1/search fans out to the services that support search and merges the results. Parameters:

Parameter	Default	Purpose
q	required	The search term.
limit	5	Maximum results per service, up to 20.
services	all	Comma-separated list, for example mail,drive. Narrows the fan-out.
semantic	false	Set true to re-rank results with AI and get a short answer. Spends your own AI credits.

Smart search with AI

semantic=true adds an AI pass over the results you already have: it reads your question, re-orders the matches by how well they answer it, adds a short reason to each, and returns a one-paragraph answer.

It is paid for with your own AI credits — the same monthly allowance the CHAMPREP AI assistant uses. Nothing is charged unless you ask for it, and keyword search never costs AI credits.

Every response reports what happened in semantic:

"semantic": { "requested": true, "applied": true, "answer": "..." }

When the AI pass cannot run, your keyword results are returned unchanged and semantic explains why:

reason	Meaning
AI_CREDITS_EXHAUSTED	You have used your monthly AI credits.
PLAN_NO_AI	Your plan does not include the AI service.
AI_UNAVAILABLE	The AI service could not be reached this time.

A failed AI pass never fails the search. Call /v1/search/services first to see whether smart search is usable — it returns semantic.available plus your remaining credits — and hide the AI option when it is not.

A service is included only when the credential holds its read scope (mail:read, drive:read, notes:read, calendar:read, chat:read, work:read, invoice:read, contacts:read) and the active plan allows it. Both checks fail closed, so a service you cannot use never contributes results.

Chat messages are encrypted at rest and are searched only inside rooms you belong to, over recent history rather than the full archive.

curl -H "Authorization: Bearer $CHAMPREP_API_KEY" \
  "https://api.champrep.com/v1/search?q=roadmap&services=mail,notes&limit=3"

Results are grouped by service and normalized to one shape, so a client renders every service the same way:

{
  "success": true,
  "data": {
    "query": "roadmap",
    "groups": [
      {
        "service": "notes",
        "label": "Notes",
        "results": [
          { "id": "6650...", "title": "Q3 roadmap", "subtitle": "Planning notes for...", "timestamp": "2026-08-02T10:14:00Z" }
        ]
      }
    ],
    "totalResults": 1,
    "searched": ["notes", "mail"],
    "skipped": [{ "service": "drive", "reason": "INSUFFICIENT_SCOPE" }],
    "cost": 2
  }
}

Read skipped before treating an empty result as “nothing found”. Each entry explains why a service was left out — INSUFFICIENT_SCOPE, NOT_IN_PLAN, or SERVICE_UNAVAILABLE when a backend was too slow or briefly unreachable. One unavailable service never fails the whole query; the rest of the results still return.

What a search costs

A search reaches one service per result group, so it is charged that way: one rate-limit unit per service actually searched. The cost field in every response tells you exactly what was charged, and X-RateLimit-Remaining reflects it before you get the response.

Request	Services searched	Cost
?q=roadmap on a plan with all eight	8	8
?q=roadmap&services=mail	1	1
?q=roadmap on a plan with only Notes	1	1

You are never charged for a service you cannot use, so narrowing with services is the cheapest way to keep an interactive search responsive. Always debounce — never send a request per keystroke.

Drive

Method	Path	Scope	Purpose
GET	/v1/drive/files	drive:read	List or search files. Use the search query when needed.
GET	/v1/drive/folders	drive:read	List root-folder contents.
GET	/v1/drive/folders/{folderId}	drive:read	List a folder’s contents.
GET	/v1/drive/starred	drive:read	List starred items.
GET	/v1/drive/recent	drive:read	List recent items.
GET	/v1/drive/shared	drive:read	List shared items.
GET	/v1/drive/quota	drive:read	Return current storage usage and availability.
POST	/v1/drive/upload	drive:write	Create an upload target.
POST	/v1/drive/files	drive:write	Save file metadata after an upload succeeds.
POST	/v1/drive/download	drive:read	Create a download target.
POST	/v1/drive/folders	drive:write	Create a folder.
POST	/v1/drive/rename	drive:write	Move or rename an item.
POST	/v1/drive/delete	drive:delete	Delete one or more items.
DELETE	/v1/drive/files/{fileId}	drive:delete	Delete a file through the legacy single-item route.

Upload is a multi-step operation: request an upload target, transfer the bytes to that target, and save the resulting metadata. Use the official SDK or CLI when you do not need to implement that sequence yourself.

Chat

Method	Path	Scope	Purpose
GET	/v1/chat/rooms	chat:read	List rooms visible to the active profile.
GET	/v1/chat/rooms/{roomId}	chat:read	Read one room.
POST	/v1/chat/rooms	chat:write	Create a room.
GET	/v1/chat/rooms/{roomId}/messages	chat:read	List room messages.
POST	/v1/chat/rooms/{roomId}/messages	chat:write	Send a room message.
GET	/v1/chat/messages/search	chat:read	Search messages.
GET	/v1/chat/unread	chat:read	Return unread counts.
GET	/v1/chat/favorites	chat:read	List favorite messages.

Calendar

Method	Path	Scope	Purpose
GET	/v1/calendar/events	calendar:read	List events; supports startDate and endDate queries.
GET	/v1/calendar/events/{eventId}	calendar:read	Read one event.
POST	/v1/calendar/events	calendar:write	Create an event.
PATCH	/v1/calendar/events/{eventId}	calendar:write	Update an event.
DELETE	/v1/calendar/events/{eventId}	calendar:write	Delete an event.
GET	/v1/calendar/upcoming	calendar:read	List upcoming meetings.
GET	/v1/calendar/invitations	calendar:read	List pending invitations.

Send event timestamps in ISO 8601 format with an explicit timezone. Event creation and updates consume the quota configured for the active plan and organization; the API does not define a universal fixed plan limit.

Contacts

Method	Path	Scope	Purpose
GET	/v1/contacts	contacts:read	List contacts.
GET	/v1/contacts/search	contacts:read	Search contacts with q or email.
GET	/v1/contacts/favorites	contacts:read	List favorites.
GET	/v1/contacts/labels	contacts:read	List labels.
GET	/v1/contacts/{contactId}	contacts:read	Read one contact.
POST	/v1/contacts	contacts:write	Add a contact.
PUT	/v1/contacts/{contactId}	contacts:write	Update contact metadata.
DELETE	/v1/contacts/{contactId}	contacts:write	Delete a contact.

Meet

Method	Path	Scope	Purpose
GET	/v1/meet/rooms	meet:read	List meeting rooms.
GET	/v1/meet/rooms/{roomId}	meet:read	Read one room.
POST	/v1/meet/rooms	meet:write	Create a room.
GET	/v1/meet/sessions	meet:read	List meeting sessions.
GET	/v1/meet/sessions/{sessionId}/participants	meet:read	List session participants.
GET	/v1/meet/recordings	meet:read	List available recordings.
GET	/v1/meet/transcriptions	meet:read	List transcriptions.
GET	/v1/meet/transcriptions/{sessionId}	meet:read	Read a final session transcription.
GET	/v1/meet/usage	meet:read	Return current meeting usage.

Recording and transcription access depends on meeting ownership, consent, retention, plan, and organization policy.

Notes

Method	Path	Scope	Purpose
GET	/v1/notes	notes:read	List notes.
GET	/v1/notes/shared	notes:read	List notes shared with the active profile.
GET	/v1/notes/{noteId}	notes:read	Read one note.
POST	/v1/notes	notes:write	Create a note.
PATCH	/v1/notes/{noteId}	notes:write	Update a note.
DELETE	/v1/notes/{noteId}	notes:write	Delete a note.
POST	/v1/notes/{noteId}/share	notes:write	Share a note using supported access settings.

Learn and courses

/v1/learn and /v1/courses expose the same curated course routes.

Method	Path	Scope	Purpose
GET	/v1/learn	courses:read	List available courses.
GET	/v1/learn/enrolled/my	courses:read	List the active user’s enrollments.
GET	/v1/learn/{courseId}	courses:read	Read one course.
GET	/v1/learn/{courseId}/sections	courses:read	List course sections.
POST	/v1/learn	courses:write	Create a course when the role permits it.
PUT	/v1/learn/{courseId}	courses:write	Update a course when the role permits it.

Use the /v1/courses prefix instead when maintaining an integration that already uses that alias.

CHAMPREP AI

Method	Path	Scope	Purpose
POST	/v1/ai/chat	ai:chat	Send a prompt or supported conversation payload.
GET	/v1/ai/conversations	ai:chat	List saved conversations.
GET	/v1/ai/conversations/{conversationId}	ai:chat	Read one conversation.
DELETE	/v1/ai/conversations/{conversationId}	ai:chat	Delete a conversation.
GET	/v1/ai/usage	ai:chat	Return current AI usage.

AI output can be incomplete or incorrect. Review important output and do not send data that the active user is not authorized to disclose.

Mail

Method	Path	Scope	Purpose
GET	/v1/mail/accounts	mail:read	List connected mail accounts.
GET	/v1/mail/emails	mail:read	List messages.
GET	/v1/mail/emails/{emailId}	mail:read	Read one message.
GET	/v1/mail/threads	mail:read	List threads.
GET	/v1/mail/threads/{threadId}	mail:read	Read one thread.
POST	/v1/mail/send	mail:send	Send a message.
GET	/v1/mail/domains	mail:read	List visible mail domains.

Work

The Work Gateway surface mirrors the supported versioned Work API beneath /v1/work. The Gateway determines the required scope from the HTTP method:

• Read methods require work:read.
• Create and update methods require work:write.
• Delete methods and destructive bulk or import-cancel actions require work:delete.

Common routes include:

Method	Path	Purpose
GET, POST	/v1/work/boards	List or create boards.
GET, PUT, DELETE	/v1/work/boards/{boardId}	Read, update, or archive a board.
GET	/v1/work/boards/{boardId}/kanban	Read the board’s Kanban view.
GET	/v1/work/boards/{boardId}/export/csv	Export a board as CSV.
GET	/v1/work/boards/{boardId}/export/json	Export a structured board snapshot.
GET, POST	/v1/work/tickets	Search or create tickets.
GET, PUT, DELETE	/v1/work/tickets/{ticketId}	Read, update, or archive a ticket.
GET	/v1/work/me/dashboard	Return the active Work dashboard summary.
GET	/v1/work/me/quota	Return current Work usage and limits.
GET, POST	/v1/work/import/jobs	List or manage supported import jobs.

Boards, tickets, sprints, automations, imports, time records, comments, attachments, saved views, and workspace membership still enforce their Work roles and resource permissions after the Gateway scope check.

Org Chart

The Org Chart surface is available beneath /v1/charts. Read methods require charts:read, create and update methods require charts:write, and delete methods require charts:delete.

Common routes include:

Method	Path	Purpose
GET	/v1/charts/me/org-chart	Read the active user’s chart.
GET	/v1/charts/me/position	Read the active chart position.
GET	/v1/charts/me/connections	Read relationship connections.
GET	/v1/charts/me/suggestions	Read relationship suggestions.
GET	/v1/charts/users/search	Search users for chart relationships.
GET	/v1/charts/orgs/{orgId}/chart	Read an organization chart.
PATCH	/v1/charts/orgs/{orgId}/config	Update chart configuration.
POST	/v1/charts/orgs/{orgId}/chart/nodes	Create a chart node.
PATCH, DELETE	/v1/charts/orgs/{orgId}/chart/nodes/{nodeId}	Update or delete a node.

Extended service surfaces

The Gateway also exposes the following versioned service prefixes:

Prefix	Read scope	Write or action scope	Delete scope
/v1/forms	forms:read	forms:write	—
/v1/invoice	invoice:read	invoice:write; send or issue actions use invoice:send	invoice:delete
/v1/qa	qa:read	qa:write	—
/v1/business	business:read	business:manage	—
/v1/billing	billing:read	billing:manage	—

These prefixes preserve the supported resource suffix beneath the Gateway while centralizing authentication, service access, scopes, rate limits, and audit context. Prefer the official service SDK or a route explicitly surfaced by the service rather than guessing resource paths from browser traffic.

Billing is a control-plane surface. It remains subject to API Gateway access, rate limits, and billing scopes even when a destination-service gate would prevent a user from repairing payment or upgrading.

Webhooks

Webhook management uses /v1/webhooks and webhooks:manage. See the dedicated webhook guide for endpoint registration, signed delivery verification, replay protection, and secret rotation.

Keep integrations current

• Use GET /v1/version for Gateway version information.
• Ignore additive response fields your client does not understand.
• Read live limit headers rather than hard-coding plan values.
• Use the least-privilege scope set.
• Follow the documentation site and SDK release notes when adopting a new route.