Skip to content
Documentation

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.

AreaPrefixScopes
Identity and profile/v1/auth, /v1/usersusers:read and credential context
Search across services/v1/searchThe read scope of each service searched
Drive/v1/drivedrive:read, drive:write, drive:delete
Chat/v1/chatchat:read, chat:write
Calendar/v1/calendarcalendar:read, calendar:write
Contacts/v1/contactscontacts:read, contacts:write
Meet/v1/meetmeet:read, meet:write
Notes/v1/notesnotes:read, notes:write
Sheets/v1/sheetssheets:read, sheets:write, sheets:share, sheets:delete, sheets:export
Docs/passthrough/docsdocs:read, docs:write, docs:share, docs:delete, docs:export
Learn/v1/learn, /v1/coursescourses:read, courses:write
CHAMPREP AI/v1/aiai:chat
Mail/v1/mailmail:read, mail:write, mail:send
Work/v1/workwork:read, work:write, work:delete
Org Chart/v1/chartscharts:read, charts:write, charts:delete
Forms/v1/formsforms:read, forms:write
Invoice/v1/invoiceinvoice:read, invoice:write, invoice:send, invoice:delete
CHAMPREP QA/v1/qaqa:read, qa:write
CHAMPREP Code/passthrough/codecode: scopes, see CHAMPREP Code
Runner Farm/passthrough/runner-farmrunner_farm:read, runner_farm:write
CHAMPREP Business/v1/businessbusiness:read, business:manage
Billing/v1/billingbilling:read, billing:manage
Webhooks/v1/webhookswebhooks: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.

MethodPathPurpose
GET/v1/versionReturn public Gateway version information.
GET/v1/auth/whoamiReturn active user, profile, credential, and plan context.
GET/v1/auth/quotaReturn the current key and Gateway quota snapshot.
GET/v1/users/meReturn the current user’s profile.
GET/v1/users/me/notificationsList 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.

MethodPathScopePurpose
GET/v1/searchPer service, see belowSearch every service this credential can reach, in one call.
GET/v1/search/servicesNoneList which services this credential is able to search.

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

ParameterDefaultPurpose
qrequiredThe search term.
limit5Maximum results per service, up to 20.
servicesallComma-separated list, for example mail,drive. Narrows the fan-out.
semanticfalseSet true to re-rank results with AI and get a short answer. Spends your own AI credits.

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:

reasonMeaning
AI_CREDITS_EXHAUSTEDYou have used your monthly AI credits.
PLAN_NO_AIYour plan does not include the AI service.
AI_UNAVAILABLEThe 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.

Terminal window
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.

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.

RequestServices searchedCost
?q=roadmap on a plan with all eight88
?q=roadmap&services=mail11
?q=roadmap on a plan with only Notes11

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.

MethodPathScopePurpose
GET/v1/drive/filesdrive:readList or search files. Use the search query when needed.
GET/v1/drive/foldersdrive:readList root-folder contents.
GET/v1/drive/folders/{folderId}drive:readList a folder’s contents.
GET/v1/drive/starreddrive:readList starred items.
GET/v1/drive/recentdrive:readList recent items.
GET/v1/drive/shareddrive:readList shared items.
GET/v1/drive/quotadrive:readReturn current storage usage and availability.
POST/v1/drive/uploaddrive:writeCreate an upload target.
POST/v1/drive/filesdrive:writeSave file metadata after an upload succeeds.
POST/v1/drive/downloaddrive:readCreate a short-lived download link bound to the calling credential.
GET/v1/drive/content/{token}drive:readStream a link issued by /v1/drive/download.
POST/v1/drive/foldersdrive:writeCreate a folder.
POST/v1/drive/renamedrive:writeMove or rename an item.
POST/v1/drive/deletedrive:deleteDelete one or more items.
DELETE/v1/drive/files/{fileId}drive:deleteDelete a file through the legacy single-item route.

Downloads take two steps: POST /v1/drive/download returns a url on the gateway that works only for the API key or session that requested it, until expiresInSeconds elapses. Fetch it with the same Authorization header; the link is not usable on its own.

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

MethodPathScopePurpose
GET/v1/chat/roomschat:readList rooms visible to the active profile.
GET/v1/chat/rooms/{roomId}chat:readRead one room.
POST/v1/chat/roomschat:writeCreate a room.
GET/v1/chat/rooms/{roomId}/messageschat:readList room messages.
POST/v1/chat/rooms/{roomId}/messageschat:writeSend a room message.
GET/v1/chat/messages/searchchat:readSearch messages.
GET/v1/chat/unreadchat:readReturn unread counts.
GET/v1/chat/favoriteschat:readList favorite messages.
MethodPathScopePurpose
GET/v1/calendar/eventscalendar:readList events; supports startDate and endDate queries.
GET/v1/calendar/events/{eventId}calendar:readRead one event.
POST/v1/calendar/eventscalendar:writeCreate an event.
PATCH/v1/calendar/events/{eventId}calendar:writeUpdate an event.
DELETE/v1/calendar/events/{eventId}calendar:writeDelete an event.
GET/v1/calendar/upcomingcalendar:readList upcoming meetings.
GET/v1/calendar/invitationscalendar:readList 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.

MethodPathScopePurpose
GET/v1/contactscontacts:readList contacts.
GET/v1/contacts/searchcontacts:readSearch contacts with q or email.
GET/v1/contacts/favoritescontacts:readList favorites.
GET/v1/contacts/labelscontacts:readList labels.
GET/v1/contacts/{contactId}contacts:readRead one contact.
POST/v1/contactscontacts:writeAdd a contact.
PUT/v1/contacts/{contactId}contacts:writeUpdate contact metadata.
DELETE/v1/contacts/{contactId}contacts:writeDelete a contact.
MethodPathScopePurpose
GET/v1/meet/roomsmeet:readList meeting rooms.
GET/v1/meet/rooms/{roomId}meet:readRead one room.
POST/v1/meet/roomsmeet:writeCreate a room.
GET/v1/meet/sessionsmeet:readList meeting sessions.
GET/v1/meet/sessions/{sessionId}/participantsmeet:readList session participants.
GET/v1/meet/recordingsmeet:readList available recordings.
GET/v1/meet/transcriptionsmeet:readList transcriptions.
GET/v1/meet/transcriptions/{sessionId}meet:readRead a final session transcription.
GET/v1/meet/usagemeet:readReturn current meeting usage.

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

MethodPathScopePurpose
GET/v1/notesnotes:readList notes.
GET/v1/notes/sharednotes:readList notes shared with the active profile.
GET/v1/notes/{noteId}notes:readRead one note.
POST/v1/notesnotes:writeCreate a note.
PATCH/v1/notes/{noteId}notes:writeUpdate a note.
DELETE/v1/notes/{noteId}notes:writeDelete a note.
POST/v1/notes/{noteId}/sharenotes:writeShare a note using supported access settings.

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

MethodPathScopePurpose
GET/v1/learncourses:readList available courses.
GET/v1/learn/enrolled/mycourses:readList the active user’s enrollments.
GET/v1/learn/{courseId}courses:readRead one course.
GET/v1/learn/{courseId}/sectionscourses:readList course sections.
POST/v1/learncourses:writeCreate a course when the role permits it.
PUT/v1/learn/{courseId}courses:writeUpdate a course when the role permits it.

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

MethodPathScopePurpose
POST/v1/ai/chatai:chatSend a prompt or supported conversation payload.
GET/v1/ai/conversationsai:chatList saved conversations.
GET/v1/ai/conversations/{conversationId}ai:chatRead one conversation.
DELETE/v1/ai/conversations/{conversationId}ai:chatDelete a conversation.
GET/v1/ai/usageai:chatReturn 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.

MethodPathScopePurpose
GET/v1/mail/accountsmail:readList connected mail accounts.
GET/v1/mail/emailsmail:readList messages.
GET/v1/mail/emails/{emailId}mail:readRead one message.
GET/v1/mail/threadsmail:readList threads.
GET/v1/mail/threads/{threadId}mail:readRead one thread.
POST/v1/mail/sendmail:sendSend a message.
GET/v1/mail/domainsmail:readList visible mail domains.

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:

MethodPathPurpose
GET, POST/v1/work/boardsList or create boards.
GET, PUT, DELETE/v1/work/boards/{boardId}Read, update, or archive a board.
GET/v1/work/boards/{boardId}/kanbanRead the board’s Kanban view.
GET/v1/work/boards/{boardId}/export/csvExport a board as CSV.
GET/v1/work/boards/{boardId}/export/jsonExport a structured board snapshot.
GET, POST/v1/work/ticketsSearch or create tickets.
GET, PUT, DELETE/v1/work/tickets/{ticketId}Read, update, or archive a ticket.
GET/v1/work/me/dashboardReturn the active Work dashboard summary.
GET/v1/work/me/quotaReturn current Work usage and limits.
GET, POST/v1/work/import/jobsList 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.

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:

MethodPathPurpose
GET/v1/charts/me/org-chartRead the active user’s chart.
GET/v1/charts/me/positionRead the active chart position.
GET/v1/charts/me/connectionsRead relationship connections.
GET/v1/charts/me/suggestionsRead relationship suggestions.
GET/v1/charts/users/searchSearch users for chart relationships.
GET/v1/charts/orgs/{orgId}/chartRead an organization chart.
PATCH/v1/charts/orgs/{orgId}/configUpdate chart configuration.
POST/v1/charts/orgs/{orgId}/chart/nodesCreate a chart node.
PATCH, DELETE/v1/charts/orgs/{orgId}/chart/nodes/{nodeId}Update or delete a node.

The Gateway also exposes the following versioned service prefixes:

PrefixRead scopeWrite or action scopeDelete scope
/v1/formsforms:readforms:write—
/v1/sheetssheets:read; export actions use sheets:exportsheets:write; sharing and publication use sheets:sharesheets:delete
/v1/invoiceinvoice:readinvoice:write; send or issue actions use invoice:sendinvoice:delete
/v1/qaqa:readqa:write—
/v1/businessbusiness:readbusiness:manage—
/v1/billingbilling:readbilling:manage—

These prefixes preserve the supported resource suffix beneath the Gateway while centralizing authentication, service access, scopes, rate limits, and audit context. Prefer 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.

CHAMPREP Code, Runner Farm, and Docs are reached through a passthrough: the Gateway forwards your request to that service’s own REST API under a fixed path, after the same key, rate-limit, plan, and scope checks as every other route. The path after the prefix is the service’s own API path.

PrefixForwardsExample
/passthrough/codeCHAMPREP Code API paths under /v1/codeGET /passthrough/code/v1/code/projects
/passthrough/runner-farmRunner Farm API paths under /v1GET /passthrough/runner-farm/v1/pools
/passthrough/docsDocs API paths under /api/v1/docsGET /passthrough/docs/api/v1/docs/documents

A path outside the allowed namespace returns 404 NOT_FOUND. Only the Gateway’s own credential reaches the service: do not send service tokens in headers or in job_token, private_token, or access_token query parameters, because the Gateway removes them.

  • GET, HEAD, and OPTIONS need at least one code: scope that can read. Other methods need code:api or a code:write_ scope.
  • CHAMPREP Code then checks the exact scope for each endpoint, the same way it checks a personal access token. For example, reading repository files needs code:read_repository, code:read_api, or code:api.
  • Paths under /v1/code/admin need a key that holds code:admin_mode by name, and an account that is a Code administrator. The wildcard and code:api do not reach them.
  • Read methods need runner_farm:read. Other methods need runner_farm:write.
  • A key never reaches connector secrets, runner tokens, the token check, pairing, or the connector’s own endpoints, and it never buys credits or changes payment settings. Use the Runner Farm app, signed in, for those.
RequestScope
GET, HEADdocs:read
A path that manages grants, share links, or publicationdocs:share
DELETE, or a path ending in /purgedocs:delete
A path ending in /exportdocs:export
Any other changedocs:write

Deleting an image inside a document is an ordinary edit and needs docs:write.

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

  • 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 release notes when adopting a new route.