Available on every plan, including the free one. The v1 API and the official SDKs are enabled for every woku account. See the plans.
This guide applies only to the v1 version of the API. It corresponds exactly to the API Reference tab you see at the top of the documentation. For the historical behavior (routes without the
/v1/ prefix), switch the version selector to v0.Interactive reference
The entire API is documented interactively in the API Reference tab of this same documentation. There you can view each endpoint with its full schema, run it live from the browser and copy examples in your preferred language. This guide is complementary: it explains the flow and the “why” of each call so that the integration takes you as little time as possible.Official SDKs
If you work in JavaScript/TypeScript or Python, you do not need to build the requests by hand. The official server-side SDKs wrap this same v1 API with a typed client that adds retries, idempotency and automatic pagination. You initialize the client with your Company Key once:- JavaScript / TypeScript: JavaScript SDK (
@wokuapp/sdk) - Python: Python SDK (
woku)
Introduction
The woku API lets you operate all feedback tools programmatically: wokus, NPS, CSAT, CES, forms and flows, as well as invitations, external trackers, ticket destinations and action plans. The typical use cases:- Create wokus automatically when an event occurs in your application (for example, closing a sale, ending a training session, delivering a product).
- Capture responses directly from your interface or backend, without redirecting the customer to the woku site: woku ratings and reviews, NPS, CSAT and CES scores, and form responses.
- Send surveys by email or WhatsApp to recipient lists from your backend.
- Capture feedback from your mobile app with a single idempotent endpoint, designed for the React Native SDK.
- Tag tools with identifiers from your systems (CRM, ERP, ticketing) to later search across them.
- Extract responses and reports into your dashboards and internal systems.
- Configure where support tickets land (Zendesk, your own service or email) and how they are routed based on your trackers.
- Manage AI-generated action plans: approve them and work them inside woku.
multipart/form-data and respond with consistent structures.
Base URL
/v1/ prefix.
Authentication
Every company registered in woku has a Company Key that is included in theAuthorization header of each request:

View of the company information window.
A missing or invalid key returns 401 Unauthorized. A valid key without access to the resource returns 403 Forbidden.
Company
Get the current company
Retrieves the data of the company associated with the Company Key. Useful to validate that your integration is authenticating with the correct account. EndpointAuthorization: Bearer <Company-Key>
200 OK: Returns the company object.401 Unauthorized: Missing or invalid key.403 Forbidden: The key is valid but the company has no access (for example, an inactive subscription or an IP outside the allowlist).
Wokus
The wokus functions let you create, query, rate and share wokus programmatically.Create a woku with a file URL
Creates a woku using an image or video hosted at a public URL (CDN, S3, ImageKit, etc.). EndpointContent-Type: application/jsonAuthorization: Bearer <Company-Key>
description(string, required): Between 3 and 140 characters.fileUrl(string, required): Public URL of an image or video (preferably.mp4).folderSecondaryKey(string, optional): Key of the folder where the woku is stored.parentFolderSecondaryKey(string, optional): Key of the parent folder. It cannot be the same asfolderSecondaryKey.clientEmail(string, optional): Email of the associated customer.clientPhone(number, optional): WhatsApp number.
201 Created: Returns the created woku object.400 Bad Request: The body did not pass validation.401 Unauthorized: Missing or invalid key.
Create a woku with a file (multipart)
When the file is in your own storage or your client uploads the image directly from a form, use the endpoint withmultipart/form-data.
Endpoint
Content-Type: multipart/form-dataAuthorization: Bearer <Company-Key>
file(binary, required): Image or video file.description(string, required): Between 3 and 140 characters.folderSecondaryKey(string, optional).parentFolderSecondaryKey(string, optional).clientEmail(string, optional).clientPhone(string, optional).
201 Created: Woku created.400 Bad Request: Validation failed (file format, size, required fields).401 Unauthorized: Missing or invalid key.
Upload media for reuse in a Woku or journey
If you need afileId before creating an instrument, send the file in the file field to POST /v1/woku-media with multipart/form-data and your Company Key. The 201 response contains fileId, filename, and type (image or video). Use that fileId with the MCP create_woku or set_journey_moment_media tool, or as toolSpec.fileId on an API Woku moment.
Real JPEG, PNG, WebP, or GIF images up to 10 MB are normalized to WebP within 1080 × 1080 pixels while preserving aspect ratio; MP4 videos can be up to 25 MB. The service inspects the contents instead of trusting the supplied extension or Content-Type. An MP4 must contain a decodable video frame. Invalid media returns 400; a multipart upload exceeding 25 MB returns 413. Codex or Claude Code can upload a local file from its terminal; see the example.
Get the data of a woku
Retrieves the woku along with its ratings and reviews. EndpointAuthorization: Bearer <Company-Key>
id(string, required): Woku identifier.
200 OK: Woku object with its reviews.401 Unauthorized: Missing or invalid key.404 Not Found: No woku with that ID exists in your company.
List the company’s wokus
Paginated list of your company’s wokus. Endpointpage(number, optional): Defaults to 1.limit(number, optional): Defaults to 20.
200 OK: Paginated list of wokus.401 Unauthorized: Missing or invalid key.
Get a woku with statistics
Returns a woku with its aggregated review statistics. Endpoint200 OK: Woku with statistics.403 Forbidden: The woku belongs to another company.404 Not Found: The woku does not exist.
List the reviews of a woku
Text and audio reviews, paginated, from most recent to oldest. Audio reviews expose their transcription. Customer contact data is never included, onlyclientId. Each review includes responseChannel: the channel it came through (whatsapp, email, review-app, widget-web, mobile-sdk, api, or a custom value you define); it is null on historical responses.
Endpoint
page(number, optional).limit(number, optional).
200 OK: Paginated list of reviews.403 Forbidden: The woku belongs to another company.404 Not Found: The woku does not exist.
Rate with a text review
Adds a rating of 1 to 5 stars with a written comment. EndpointContent-Type: application/jsonAuthorization: Bearer <Company-Key>
qualification(integer, required): Value between 1 and 5.description(string, required): Text review, maximum 3000 characters.clientEmail(string, optional): If not provided,anonymousmust betrue.clientPhone(number, optional).anonymous(boolean, optional): Defaults tofalse.responseChannel(string, optional, max 48): Channel the response came through. Canonical values:whatsapp,email,review-app,widget-web,mobile-sdk,api. You can also send your own custom value, which replaces the default. Defaults toapi.
201 Created: Review recorded (held: false). If the company has no opinion credits left, the response carriesheld: true: the opinion is kept on hold, theidbelongs to that hold and not to a review, and it is recorded automatically once the company tops up its credits.400 Bad Request: Validation failed.401 Unauthorized: Missing or invalid key.404 Not Found: The woku does not exist.
Rate with an audio review
Upload an audio file along with the rating. EndpointContent-Type: multipart/form-dataAuthorization: Bearer <Company-Key>
file(binary, required): Audio. Recommended.mp4or.wav.qualification(string"1","5", required).clientEmail(string, optional).clientPhone(string, optional).anonymous(string"true"or"false", optional).responseChannel(string, optional, max 48): Channel the response came through. Canonical values:whatsapp,email,review-app,widget-web,mobile-sdk,api. You can also send your own custom value, which replaces the default. Defaults toapi.
201 Created: Review recorded (held: false). If the company has no opinion credits left, the response carriesheld: true: the opinion is kept on hold, theidbelongs to that hold and not to a review, and it is recorded automatically once the company tops up its credits.400 Bad Request: Validation failed.401 Unauthorized: Missing or invalid key.404 Not Found: The woku does not exist.
Share a woku by email
Sends the woku to one or more recipients. It is the same flow that starts from the share interface. EndpointContent-Type: application/jsonAuthorization: Bearer <Company-Key>
200 OK: Send queued.400 Bad Request: Validation failed (malformed email, both fields empty, etc.).401 Unauthorized: Missing or invalid key.
Mobile SDK captures
A single ingestion endpoint designed for the React Native SDK. It receives a normalized capture and routes it according to itskind: woku (a woku review), nps, csat or ces. The response channel is sealed as mobile-sdk on the server side.
Endpoint
application/json: text or rating captures. The body is the capture.multipart/form-data: captures with audio. The file goes in thefilefield and the capture as JSON in thepayloadfield. Audio is available forwokuandnps; audio comments are not yet supported forcsatorces.
id(string, optional): Identifier generated by the client. It is used as the idempotency key.kind(string, required):woku,nps,csatorces.targetId(string): Id of the woku (required forwoku), of the NPS Tool (optional fornps) or of the CSAT/CES Tool (required forcsatandces).rating(integer, optional): Woku rating, from 1 to 5.score(integer, optional): NPS score from 0 to 10, or CSAT/CES from 1 to 5.comment(string, optional, max 3000): Text comment. Required in text captures of a woku.respondent(object, optional):email,phone,externalId. Without an identifier, the capture stays anonymous.
X-Woku-Idempotency-Key header or, in its absence, from the id field of the body. If the same send is retried (for example, by the SDK’s offline queue), the API returns the already-recorded result instead of creating a duplicate.
Responses
201 Created: Capture accepted. Returnsid,kind,remoteIdandstatus: "accepted".400 Bad Request: Validation failed (missingtargetId, audio incsatorces, malformedpayload).401 Unauthorized: Missing or invalid key.409 Conflict: The tool accepts one response per client and this client already answered (code: "ALREADY_RESPONDED").
NPS responses
You can capture NPS scores and extract individual responses into your systems. Aggregated reports are in the NPS Reports section.Capture an NPS score
Endpointscore(integer, required): From 0 to 10.npsToolId(string, optional): Specific NPS Tool. If omitted, the score is recorded at the company level.clientEmail(string, optional): If not provided, the response stays anonymous.anonymous(boolean, optional).responseChannel(string, optional, max 48): Channel the response came through. Canonical values:whatsapp,email,review-app,widget-web,mobile-sdk,api. You can also send your own custom value, which replaces the default. Defaults toapi.
201 Created: ReturnsnpsIdand the response object.400 Bad Request: Validation failed.403 Forbidden: The NPS Tool does not belong to your company.409 Conflict: The tool accepts one response per client and this client already answered (code: "ALREADY_RESPONDED").
Add a review to an NPS score
Once the score is created, you can attach an optional text or audio review to it. Endpoints- Text: JSON body
{ "description": "..." }, maximum 3000 characters. - Audio:
multipart/form-datawith the file in thefilefield (m4a, aac or mp4). The transcription is generated on the server.
201 Created: Review attached.400 Bad Request: Validation failed.403 Forbidden: The NPS belongs to another company.404 Not Found: The NPS does not exist.
Query NPS Tools and responses
Read endpoints to bring NPS data into your systems:GET /v1/nps-tools: Paginated list of your company’s NPS Tools.GET /v1/nps-tool/:id: Definition of an NPS Tool (to build the question).GET /v1/nps: Paginated responses, from most recent to oldest.GET /v1/nps/:id: An individual response.
GET /v1/nps accepts the filters npsToolId, from and to (ISO dates over the creation date) and withFeedback=true (only responses with a text or audio review), plus page and limit. Responses never include customer contact data, only clientId. Each response includes responseChannel: the channel it came through (whatsapp, email, review-app, widget-web, mobile-sdk, api, or a custom value you define); it is null on historical responses.
CSAT and CES
The CSAT (satisfaction, scale 1 to 5) and CES (effort, scale 1 to 5) families are exact mirrors. The examples usecsat; replace csat with ces and csatToolId with cesToolId to get the CES family. Unlike NPS, the tool id is always required: CSAT and CES are always custom surveys.
Capture a CSAT score
Endpointscore(integer, required): From 1 to 5.csatToolId(string, required): CSAT Tool that answers the survey.clientEmail(string, optional): If not provided, the response stays anonymous.anonymous(boolean, optional).responseChannel(string, optional, max 48): Channel the response came through. Canonical values:whatsapp,email,review-app,widget-web,mobile-sdk,api. You can also send your own custom value, which replaces the default. Defaults toapi.
201 Created: ReturnscsatIdand the response object.400 Bad Request: Validation failed.403 Forbidden: The CSAT Tool does not belong to your company.409 Conflict: The tool accepts one response per client and this client already answered (code: "ALREADY_RESPONDED").
Add a comment to a CSAT response
Endpoints- Text: JSON body
{ "description": "..." }, maximum 3000 characters. - Audio:
multipart/form-datawith the file in thefilefield (m4a, aac or mp4). The transcription is generated on the server.
201 Created: Comment accepted.403 Forbidden: The response belongs to another company.404 Not Found: The CSAT response does not exist.
Query CSAT tools and responses
GET /v1/csat-tools: Paginated list of your company’s CSAT Tools.GET /v1/csat-tool/:id: Definition of a CSAT Tool (to build the survey).GET /v1/csat: Paginated responses, with the filterscsatToolId,from,toandwithFeedback.GET /v1/csat/:id: An individual response.
responseChannel: the channel it came through (whatsapp, email, review-app, widget-web, mobile-sdk, api, or a custom value you define); it is null on historical responses.
The CES family exposes exactly the same endpoints: POST /v1/ces, POST /v1/ces/:id/textnotes, POST /v1/ces/:id/voicemails, GET /v1/ces-tools, GET /v1/ces-tool/:id, GET /v1/ces and GET /v1/ces/:id.
NPS, CSAT and CES response settings
POST /v1/{nps,csat,ces}-tools and PATCH /v1/{nps,csat,ces}-tools/:id take two settings, and every tool returns them:
anonymousDisabled(boolean): only identified responses (email or phone) are accepted.onlyOneResponsePerClient(boolean): each identified client answers only once. A second answer gets409 Conflictwithcode: "ALREADY_RESPONDED". Anonymous answers do not count.
PATCH must carry only these fields, because the survey text is fixed.
Forms
Query and capture forms from your own systems: render the form with its definition, submit responses and extract the results.List the company’s forms
Endpointpage(number, optional).limit(number, optional).
200 OK: Paginated list of forms.401 Unauthorized: Missing or invalid key.
Get the definition of a form
Returns the active form (fields, configuration, localized content) along with the company’s branding, to render it in your own interface. Endpoint200 OK: Form definition.403 Forbidden: The form belongs to another company.404 Not Found: It does not exist or is inactive.
Submit a form response
Endpointanonymous(boolean, required).email/phone(string, optional): Required depending on how the form identifies customers, when the response is not anonymous.answers(object, required): Answers by field id. They are validated against the form definition.responseChannel(string, optional, max 48): Channel the response came through. Canonical values:whatsapp,email,review-app,widget-web,mobile-sdk,api. You can also send your own custom value, which replaces the default. Defaults toapi.
201 Created: Response recorded.400 Bad Request: Validation failed or the form is closed.403 Forbidden: The form belongs to another company.404 Not Found: It does not exist or is inactive.429 Too Many Requests: The respondent is in quarantine.
List the responses of a form
Paginated, from most recent to oldest. Responses expose the values by field id and never include customer contact data, onlyclientId. Each response includes responseChannel: the channel it came through (whatsapp, email, review-app, widget-web, mobile-sdk, api, or a custom value you define); it is null on historical responses.
Endpoint
200 OK: Paginated list of responses.403 Forbidden: The form belongs to another company.404 Not Found: The form does not exist.
Flows
A flow chains ordered steps, each a woku or an NPS, CSAT or CES tool, into a survey sequence. It differs from Customer journeys, which evaluate business moments and can advance by delays or webhooks. With the flow data you can render its sequence in your application and capture with the existing endpoints (POST /v1/wokus/:id/textnotes, POST /v1/nps, POST /v1/csat, etc.). A flow does not live inside folders.
GET /v1/flows: Paginated list of your company’s flows, each with itssteps.GET /v1/flows/:id: Flow data: ordered steps with their tools, branding and linked NPS.POST /v1/flows: Creates a flow with anameand 1 to 20steps. AcceptsX-Woku-Idempotency-Key.PATCH /v1/flows/:id: Changes thenameor replaces the full list ofsteps.DELETE /v1/flows/:id: Deletes the flow. Its tools and responses are kept.
{ "type": "woku" | "nps" | "csat" | "ces", "toolId": "<id>" }. A tool appears once, all of them must belong to your company, and a closed woku or one-review-per-customer woku cannot be a step. For an nps step, your company id as toolId is the company-level NPS.
200 OKor201 Created: Flow data or paginated list.400 Bad Request: Invalid steps (repeated, too many or a tool that is not allowed).403 Forbidden: The flow belongs to another company.404 Not Found: The flow or a tool of the steps does not exist.
Invitations
A homogeneous family of endpoints to send surveys by email or WhatsApp to a list of up to 100 recipients. Sends are asynchronous: the API responds immediately with the per-recipient detail. Endpointschannel(string, required):emailorwhatsapp.recipients(string[], required, max 100): Emails for theemailchannel; numbers with country code (for example56912345678) forwhatsapp.language(string, optional):esoren.npsToolId(string, optional, NPS only): If omitted, the company-level NPS survey is sent.csatToolId/cesToolId(string, required in CSAT and CES).
202 Accepted: Per-recipient summary:accepted(dispatched or queued) andrejectedwith the reason (invalid_recipient,quarantined,insufficient_credits_or_blocked,send_failed).400 Bad Request: Validation failed, or the form or woku is closed.403 Forbidden: The tool does not belong to your company.404 Not Found: The form or the woku does not exist.
Folders and tools
One folder tree holds wokus and NPS, CSAT and CES tools. The Folders and tools guide explains the model; this section summarizes the endpoints. All of them use your Company Key.Folders
GET /v1/folders: lists every folder, or only the subfolders ofparentFolderId. Acceptsqto search by name.POST /v1/folders: creates a folder (name, and optionallyparentFolderIdandcolor). AcceptsX-Woku-Idempotency-Key.GET /v1/folders/:id: one folder with its path, itsorigin(andintegrationProvideron integration folders) and the stats of its subtree.PATCH /v1/folders/:id: changesname,color(nullclears the color) orwhatsappAlertRecipients(replaces the WhatsApp numbers alerted on improvement comments of the folder, or on every review withallReviews: true;[]clears them).PATCH /v1/folders/:id/move: moves the folder underparentFolderId, or to the root withnull.DELETE /v1/folders/:id: deletes the folder. Its content moves up to the parent folder. If ticket destinations or plan groups are configured on that folder, they are deleted with it together with their tickets and plans: without?confirmDependents=truethe response is409withcode: "FOLDER_HAS_DEPENDENTS"and the list independents.GET /v1/folders/:id/report: AI report over every tool of the folder and its subfolders (regenerate,lang).GET /v1/folders/:id/metrics: figures of each tool of the folder and its subfolders over a period (days: 7, 30, 90 or 0 for the whole history) against the previous period, with the daily sums and the histogram of scores.GET /v1/folders/:id/csv: CSV with one row per response, or only those of a period withfromandto(ISO 8601,toexclusive).GET /v1/folders/:id/pdf: the folder report as a PDF, with a breakdown per type (lang).
Tools
GET /v1/tools: folders and tools of every type in a cursor-paginated list, with search (q), filters (types,folderId,scope, dates,trackers), sorting (sort, also by the latest response withlastResponse) and counts per type.foldersLimitandfoldersCursorpage the folders (“see more”; the response carriesfoldersNextCursor).GET /v1/tools/stats: figures per type on their native scale, for the company or a folder (folderId) and a period (from,to).GET /v1/tools/metrics: the metrics of the company report of one type (type:woku,nps,csatorces), with the same per-tool figures asGET /v1/folders/:id/metricsfor every tool of that type in the company (root and folders), over a period (daysorfrom/to) against the previous one.POST /v1/tools/move: moves up to 200 items of mixed types to a folder (folderId) or to the root (null).folderIdwhen creating withPOST /v1/nps-tools,POST /v1/csat-toolsandPOST /v1/ces-tools, andPATCH /v1/{nps,csat,ces}-tools/:id/moveto move them.
Folder participants
The list of people who should answer the tools of the folder and who already did. Details in Folder participants.GET /v1/folders/:id/participants: the list and, per tool,responded,missing,repeated,outsideListandanonymousAllowed.PUT /v1/folders/:id/participantsandPOST /v1/folders/:id/participants: replace the list or add people to it (text, one person per line, up to 500).DELETE /v1/folders/:id/participants/:participantIdandDELETE /v1/folders/:id/participants: remove one person or delete the list.POST /v1/folders/:id/participants/resend: resends a tool to the missing, by email or WhatsApp.
Scheduled report emails
The PDF report of a folder or of a tool by email, every month, every two weeks, every week or once. Details in Scheduled report emails.GET /v1/report-subscriptionsandPOST /v1/report-subscriptions: list and create scheduled reports.PATCH /v1/report-subscriptions/:id: edits, pauses or resumes a recurring one.DELETE /v1/report-subscriptions/:id: deletes it.POST /v1/report-subscriptions/:id/send: sends it now.
Journeys in folders
GET /v1/journey-folders: status of the journey folder organization (enabled,organizing,pending).POST /v1/journey-folders/organize: switches it on and runs a one-off pass in the background (202;409if one is already running).folderIdandmomentFoldersonGET /v1/journeysandGET /v1/journeys/:id, andoriginon the folders ofGET /v1/foldersandGET /v1/tools.
NPS Reports
If your company uses the NPS tool, you can query the aggregated reports directly from the API to integrate them into your own dashboards.Company NPS report
Returns the aggregated report of all NPS recorded for your company. EndpointAuthorization: Bearer <Company-Key>
200 OK: Report with the distribution of promoters, passives and detractors, and the resulting NPS score.401 Unauthorized: Missing or invalid key.
Company woku report
Returns the AI report over every woku of your company, at the root and in every folder, with the same text sections as a folder report. EndpointAuthorization: Bearer <Company-Key>
200 OK: Company woku report.401 Unauthorized: Missing or invalid key.
NPS report for a tool
Returns the report of a specific NPS Tool (for example, “post-event NPS” or “post-purchase NPS”). EndpointAuthorization: Bearer <Company-Key>
id(string, required): NPS Tool identifier.
200 OK: NPS Tool report.400 Bad Request: Malformedid.401 Unauthorized: Missing or invalid key.404 Not Found: The NPS Tool does not exist or does not belong to your company.
External Trackers
External trackers let you associate identifiers from your systems (CRM, ERP, ticketing, OMS) with your feedback tools (wokus, NPS, CSAT, CES, forms and flows) to later search across them. For example: linking a woku to your CRM’stransaction_id or your ERP’s order_id.
Model
- Tracker definition: A company-level catalog entry, such as
{ name: "trr", system: "crm interno", description: "..." }. It is defined in woku’s admin panel, in the Company section. - Tracker value: A string value tied to a
(tool, Tracker)pair. Several tools can share the same value.
List the company’s active trackers
Endpointpage(number, optional).limit(number, optional).
200 OK: Paginated list of tracker definitions.401 Unauthorized: Missing or invalid key.
List trackers assigned to a woku
Endpoint200 OK: Trackers assigned to the woku.401 Unauthorized: Missing or invalid key.
Assign a tracker value to a woku
Creates or updates (upsert) the value of a tracker on a woku. Endpointname(string, required, max 60): Name of the tracker defined in your company.value(string, required, max 500): Value of the external identifier (always stored as a string).
201 Created: Value assigned or updated.400 Bad Request: Validation failed.401 Unauthorized: Missing or invalid key.404 Not Found: The woku or the tracker does not exist.
Delete a tracker value from a woku
Endpoint200 OK: Deleted.401 Unauthorized: Missing or invalid key.404 Not Found: The woku or the tracker does not exist.
Search wokus by tracker
Finds all wokus that have a given(name, value). Useful to get back from your CRM to the corresponding woku.
Endpoint
name(string, required): Tracker name.value(string, required): Value to search for.page(number, optional).limit(number, optional).
200 OK: Paginated list of wokus with their tracker values.401 Unauthorized: Missing or invalid key.404 Not Found: No matches exist.
Trackers on VoC tools (NPS, CSAT, CES, forms, flows)
In addition to wokus, you can assign trackers to the other feedback tools. The tool type goes in the route as:entityType, with one of these values: nps, csat, ces, form, flow. The :id is the tool id (for example npsToolId, csatToolId, cesToolId, formId or flowId).
In version 2 of the API these endpoints and the woku ones will be unified into a single polymorphic resource.
List trackers assigned to a tool
EndpointGET /v1/external-trackers/nps/671000000000000000000001.
Responses
200 OK: Trackers assigned to the tool.400 Bad Request: Unsupported tool type.401 Unauthorized: Missing or invalid key.
Assign a tracker value to a tool
Creates or updates (upsert) the value of a tracker on the tool. Endpointname(string, required, max 60): Name of the tracker defined in your company.value(string, required, max 500): Value of the external identifier (always stored as a string).
201 Created: Value assigned or updated.400 Bad Request: Unsupported type, inactive tracker or validation failed.403 Forbidden: The tool belongs to another company.404 Not Found: The tool or the tracker does not exist.
Delete a tracker value from a tool
Endpoint200 OK: Deleted.404 Not Found: The tracker or the assignment does not exist.
Ticket destinations
Ticket destinations define where the support tickets generated by woku’s AI land: Zendesk, your own HTTP service or a list of emails. Each destination has routing rules based on your external trackers that decide which tickets reach it.Model
kind(required):zendesk,customoremail.config(required): non-sensitive configuration, specific to eachkind.zendesk:{ connectionId, groupId? }.connectionIdis the id of your Zendesk Integration connected in the admin panel;groupIdis the agent group, optional.custom:{ url, method, headers? }.methodisPOSTorPUT;headersare extra non-sensitive headers.email:{ emails }. Up to 20 recipients.
credentials(required, write-only): never returned in the responses, only itscredentialsHint(last 4 masked characters). Zendesk authenticates with your company’s connected Integration, so you send{}. Custom uses{ authType, ... }, withauthTypenone,basic(addsusername,password),bearer(addstoken) orapi-key-header(addsheaderName,headerValue). Email also uses no credentials, you send{}.routingConditions(optional, up to 20 rows): conditions over your external trackers. Each row uses the operatorequals(the tracker must have an exact value invalue) orany(any value of the tracker,valueis omitted).relationToPreviousjoins a row with the previous one (ANDsame group,ORnew group); the first row does not include it. The destination receives the ticket when some OR group is fully satisfied.scopeKind(optional,trackersby default):trackersroutes byroutingConditions;folderroutes by a tool folder and receives the tickets of every tool inside it, at any depth. Never both: withfolderno conditions are sent, and switching tofolderclears the existing ones.folderId(required withscopeKind: "folder"): id of the folder. If you delete that folder, the destination is deleted with it, together with its tickets.
List the ticket destinations
EndpointfolderId(string, optional): only destinations by folder that listen to that folder (configured on it or on a parent folder).
200 OK: List of destinations (without credentials).401 Unauthorized: Missing or invalid key.
Get a ticket destination
Endpoint200 OK: Destination.401 Unauthorized: Missing or invalid key.404 Not Found: The destination does not exist.
Create a ticket destination
EndpointContent-Type: application/jsonAuthorization: Bearer <Company-Key>
name(string, required, max 120).kind,config,credentials,routingConditions: see the Model section of this part.aiContext(string, optional, max 2000): additional context for the AI triage of this destination.template(object, optional, onlykind: "custom"):{ preset, body? }. Withoutbody, the canonical ticket envelope is sent.
201 Created: Destination created.400 Bad Request: Validation failed.401 Unauthorized: Missing or invalid key.
Update a ticket destination
Endpointcredentials rotates the stored secret. Sending kind changes the provider: config and credentials are validated against the new kind.
Body (example: disable)
200 OK: Destination updated.400 Bad Request: Validation failed.401 Unauthorized: Missing or invalid key.404 Not Found: The destination does not exist.
Delete a ticket destination
Endpoint200 OK:{ "deleted": true }.401 Unauthorized: Missing or invalid key.404 Not Found: The destination does not exist.
Action plan groups
An action plan group defines which feedback (by tracker conditions) generates an improvement plan and who the owners are. When the counter of new improvement-type comments reaches the group’sthreshold, woku drafts a plan with AI for its members.
Model
scopeKind(optional,trackersby default):trackerslistens byconditions;folderlistens to every tool inside a folder, at any depth. Never both.conditions(required withscopeKind: "trackers", minimum 1 row, up to 20; not sent withfolder): same rules as theroutingConditionsof ticket destinations (operatorequalsorany,relationToPreviousto build AND/OR).folderId(required withscopeKind: "folder"): id of the folder. If you delete that folder, the group is deleted with it, together with its plans.members(required, minimum 1): each withuserIdandrole(adminapproves and sends plans,assigneeworks the tasks). A group needs at least oneadminand oneassignee.threshold(integer, optional, minimum 1, defaults to 300): new improvement-type comments that trigger a draft.enabled: a disabled group stops counting feedback and generating drafts, but keeps its history and statistics.
List the action plan groups
Endpointsearch(string, optional): free search by name, description and condition values.folderId(string, optional): only groups by folder that listen to that folder (configured on it or on a parent folder).
200 OK: List of groups.401 Unauthorized: Missing or invalid key.
Get an action plan group
Endpoint200 OK: Group.401 Unauthorized: Missing or invalid key.404 Not Found: The group does not exist.
Create an action plan group
EndpointContent-Type: application/jsonAuthorization: Bearer <Company-Key>
name (string, required, max 120) and description (string, optional, max 500).
Responses
201 Created: Group created.400 Bad Request: Validation failed.401 Unauthorized: Missing or invalid key.
Update an action plan group
Endpointdescription: "" clears it.
Responses
200 OK: Group updated.400 Bad Request: Validation failed.401 Unauthorized: Missing or invalid key.404 Not Found: The group does not exist.
Enable or disable a group
Endpoint200 OK: Group updated.401 Unauthorized: Missing or invalid key.404 Not Found: The group does not exist.
Delete an action plan group
Endpoint200 OK:{ "deleted": true }.401 Unauthorized: Missing or invalid key.404 Not Found: The group does not exist.
Action plans
Action plans are improvement plans drafted by AI from the feedback of a group. A plan is born indraft state, is approved, and from there it is worked inside woku with the internal provider (“Manage in woku”, an internal kanban).
Model
status:draft,approved,sent,canceled,delivery_error,in_progress(managed inside woku) orcompleted.priority:high,mediumorlow, calculated by woku (never defined by the AI).evidence: the slice of feedback frozen at the moment the plan is generated; its numbers are never recalculated.tasks: the plan’s task list. In a managed plan (in_progress) each task also hasstatus(todo,in_progress,done) andassigneeId.
List the action plans
EndpointgroupId,status,source(woku,nps,csatorces),priority,from,to,search,page,limit: all optional.
200 OK:{ "data": [...], "total": 42 }. Unlike other listings in this API, this response does not repeatpageorlimit.401 Unauthorized: Missing or invalid key.
Get an action plan
Endpoint200 OK: Plan.401 Unauthorized: Missing or invalid key.404 Not Found: The plan does not exist.
Manage a plan inside woku
Endpointapproved (or delivery_error to retry). With provider: "internal" the plan is managed inside woku: it carries no target and applies immediately (the plan moves to in_progress).
Body
provider(string, required):internal(manage the plan inside woku). It is the only provider available on the public API.resourceLabel(string, optional, max 300): human-readable description of the destination.
202 Accepted:{ "status": "managed" }.401 Unauthorized: Missing or invalid key.404 Not Found: The plan does not exist.409 Conflict: The plan is not in a valid state for this transition, or a send is already in progress.
Tasks of a plan
Available while the plan is indraft or in_progress (managed). A task’s status and assigneeId can only be edited in a managed plan.
Endpoints
- Add (
POST .../tasks): body{ "text": "..." }, maximum 160 characters, up to 100 tasks per plan. - Reorder (
PATCH .../tasks/reorder): body{ "orderedTaskIds": [...] }with ALL the plan’s task ids, in the desired order. - Edit (
PATCH .../tasks/:taskId): body with at least one oftext,statusorassigneeId. - Delete (
DELETE .../tasks/:taskId): no body.
200 OK(201 Createdwhen adding): Plan updated.400 Bad Request: Validation failed.401 Unauthorized: Missing or invalid key.404 Not Found: The plan or the task does not exist.409 Conflict: The plan is not indraftorin_progress, orstatus/assigneeIdwas sent in a non-managed plan.
Change the state of a plan
Endpoints
Responses
200 OK: Plan updated.401 Unauthorized: Missing or invalid key.404 Not Found: The plan does not exist.409 Conflict: The plan is not in the source state required for that action.
Ingestion and extraction limits
The REST API is documented interactively in the API Reference tab and applies rate and volume limits both for ingestion (creation of wokus, reviews, NPS, tracker assignment) and for extraction (querying wokus, reports and searches). The limits cover the two modes of operation: per event (one call per record) and per batch (batch loads). The limits are applied per Company Key:These are the default limits of the Corporate plan. If your integration
needs larger windows (seasonal peaks, massive migrations),
write to us to expand them.
Handling 429 (Too Many Requests)
When you exceed a rate limit, the API responds with429 Too Many Requests
and includes headers that tell you when to retry:
Retry-After: seconds to wait before the next attempt.X-RateLimit-Limit: cap of the current window.X-RateLimit-Remaining: remaining requests in the window.X-RateLimit-Reset: timestamp at which the window resets.
Retry-After.
For batch loads, split the batches that exceed the maximum number of records
instead of retrying the whole batch.
Pagination in extraction
The extraction endpoints that return collections are paginated. Control the page with the query paramspage and limit (for example, in
GET /v1/external-trackers or GET /v1/external-trackers/search). To
extract large volumes, iterate through the pages sequentially respecting
the per-minute extraction limit and the maximum number of records per page.
Common errors
Inaccessible file URL
If you usePOST /v1/wokus with fileUrl, make sure the URL is publicly accessible. Our service downloads the file before creating the woku.
Duplicate secondary key
folderSecondaryKey is used to identify a folder within your company. Two folders with the same key cannot exist in the same company. If you need to reuse a key, first delete the existing folder from the admin panel.
401 on every call
The key is missing, wrong or was regenerated. Get it again from admin.woku.app → Company information → Get Key.403 on every call
The key is valid but the company has no access: the subscription is not active or the call comes from an IP outside the allowlist in Company → Security.Contact and support
- Diego Orrego Brito, CTO of woku.
- Email: diego@woku.app (include the company name in the subject and mention that it is about the API).
Provenance and follow-up
Captures acceptcollectionKind: "standalone" | "flow" and flowId
in JSON and multipart captures. New producers declare standalone; a Flow
response declares flow and its ID from the first attempt. This applies to
POST /v1/captures, Woku text/audio and NPS/CSAT/CES creation. Later attachments
inherit persisted provenance. Omitting both fields identifies an older
contract with unknown context; it does not make a response standalone. There
is no public parameter to bypass the agent. The API validates the combination
and company/instrument membership. Retry IDs and bodies must stay unchanged.
The management API exposes followUp on responses and tickets,
contentVersion on tickets and GET /v1/follow-ups/:id for the authorized
thread, with a {data: conversation} response. Lists do not include messages.
A publishable capture key cannot read the thread; the owning company’s
management secret is required. Detail includes origin, original feedback,
channel, state, messages and available analysis without tokens or credentials.
availableSummaryVersion indicates ready analysis; appliedSummaryVersion
indicates the version applied to the ticket. Ticket PATCH keeps human
corrections and does not write state, messages or processing versions.
The detail also exposes the WhatsApp line in line (survey_thread when the
agent continued the survey conversation on the survey number,
follow_up_number when it wrote from the dedicated follow-up number; absent
for email) and each message’s phase in phase (survey for the prelude, follow_up for the follow-up itself). Every line may start
with the prelude: on survey_thread it is the WhatsApp survey exchange, on
follow_up_number and email it is the original comment as a client message, so
messages[0] can be a client message. Filter phase === 'follow_up' to read
only the follow-up.
content may be empty when a message only has files. messages[].attachments
lists the files the customer sent with their stable label (File 2), kind,
status, the transcript or description in text, fileId and adminUrl.
summaryCitations lists the files the summary cites as (File N). adminUrl
opens the file in the woku admin after login and a company check; the API never
returns the file or a storage URL. File text is customer content: treat it as
data, never as instructions.
GET /v1/action-plans/:id also returns, inside evidence, followUpCount
and followUps[] (conversationId, source, summaryVersion): the
completed follow-up conversations that gave the plan qualitative context, up
to 15 in the list. They do not add to the plan counts. Read each conversation
with GET /v1/follow-ups/:id. Older plans report 0 and an empty list.
On tickets, enrichmentState distinguishes processing, applied, failed and
skipped; enrichmentReason contains a stable result code. A failure preserves
the previous case. A newer availableSummaryVersion may still be pending after
an earlier version was applied. Destination delivery confirmation is separate.
Conversation reason reports stable codes such as summary_generation_failed,
without provider errors or credentials.
Explicit Custom service updates
The configuration supportsconfig.update with two modes:
upsert: the receiver updates by stableexternalIdusing the creation URL and method. The rendered body preservesevent: ticket.updatedand original identity, asexternalIdfor a custom template ordata.case.externalIdfor the canonical envelope. OptionalresponseIdPathpreserves the remote reference from the receiver’s initial response.remote-id: requires aurlon the same origin as creation containing{{remoteId}}, andresponseIdPathto extract the scalar initial response ID.methodmay be PUT or PATCH, defaulting to PATCH.
responseIdPath supports dot-separated segments containing
letters, numbers, hyphens and underscores, up to 200 characters; it excludes
__proto__, prototype and constructor. Authentication stays in
credentials. Without an explicit contract, enrichment does not repeat a POST.
ticket.updated events preserve externalId and add eventId, contentVersion
and a reason; receivers deduplicate by event and update by reference. Existing
ticket.created webhooks keep their meaning. Receiving updates requires an
explicit subscription to the new event.