Store API
Read each branch's address, map pin, weekly hours, closed days, open state, own channels and people, and each channel's Store choice; add, change or archive branches as the Store page's editor does.
GET /v1/store/branches → POST /v1/store/branches → PATCH /v1/store/branches/:id → PATCH /v1/store/channels/:idScopes store:readstore:write6 endpointsShow
Reading branches
Keys need store:read, offered in Settings › API keys only while the workspace has Store. Every endpoint checks the module again; while it is off it answers403 with details.reason store_off. A key keeps its scope after Store is switched off.
The list follows the Store page's order, with active branches by default. Use q to search by name, city or zip, ignoring case and accents, andinclude_archived=true to include archived branches. Use limit andoffset for paging. Each branch's open state uses its own timezone, weekly windows and closures. People expose only ids and names, never emails.
GET /v1/store/channels lists each channel's Store choice as Store settings shows it: a branch's own (with its branch), shared (the AI asks the customer's city and offers the nearest branch) or not a Store channel. Each one names the AI agent that answers it and what a request that comes in there gets in requests: its channel's branch, the nearest one, or none, with the reason. Filter by mode or branch_id.
PATCH /v1/store/channels/:id changes that choice with store:write: send mode branch with a branch_id, shared, or none. It runs Store settings' own route as the member who created the key, so the screen's rules hold: an active branch of the workspace, and a key created by an owner, admin or builder. A key gets store:write only when it's given on its own in Settings › API keys; no preset or default gives it.
MCP offers list_store_branches, get_store_branch, list_store_channels and set_store_channel with the same scope and module checks, and the branch changes below. Requests use Tickets' tickets:read and tickets:write scopes.
Adding, changing and archiving branches
Keys need store:write, offered like store:read only while the workspace has Store and given to a key only on its own. POST /v1/store/branches adds a branch and PATCH /v1/store/branches/:id changes one. Both run the Store page's own route as the member who created the key, so the page's rules hold: a key created by an owner, admin or builder, and the same checks as its editor (a name unique among the active branches, a manager and salespeople who can work tickets, the workspace's own channels, hours of up to two windows a day, one closure a day and a readable Google Maps link). Both answer the branch as GET reads it.
A field left out of a PATCH stays as it is. hours, closures, salespeople_ids and channel_ids each replace the branch's whole list, so send the list back with the change; a channel another branch had becomes this one's. closures are the days from the workspace's yesterday on, as GET reads them; earlier ones stay. manager_id alone keeps the salespeople, and salespeople_ids alone keeps the manager. archived: true, sent alone, archives the branch: it leaves the lists and the AI's choices, its channels become shared and its requests keep it. An archived branch can't be changed.
A key whose changes wait for approval gets 202 with data.change_request for a change, and for adding a branch with channel_ids, which takes those channels from where they were; archiving waits as a delete does. MCP offers create_store_branch, update_store_branch and archive_store_branch when the key's owner lets MCP set up the workspace.
/v1/store/branchesList store branches
The workspace's active branches in the Store page's order (position, then name), with their address, pin, hours, closures, open state, own channels and people.
store:readQuery parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
include_archivedtrue | falsetrue includes archived branches. Default: false.
qstring · 1–120 charactersSearch by name, city or zip, ignoring case and accents.
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).403forbiddenStore is not enabled for this workspace. NuTalk switches the module on per workspace (details.reason store_off).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/store/branches?q=Monterrey&limit=20" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "b6f9a520-1f1e-4c2a-9a55-2d6d3f1c9e30",
"name": "Monterrey Centro",
"kind": "branch",
"address": "Calle Ejemplo 120",
"city": "Monterrey",
"postal_code": "64000",
"map_pin": {
"latitude": 25.67,
"longitude": -100.31,
"google_maps_url": "https://www.google.com/maps?q=25.67,-100.31"
},
"hours": {
"tz": "America/Monterrey",
"days": {
"1": [
[
"09:00",
"19:00"
]
],
"2": [
[
"09:00",
"19:00"
]
]
}
},
"closures": [
{
"date": "2026-12-25",
"reason": "Navidad"
}
],
"open_now": true,
"closes_at": "19:00",
"channels": [
{
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Chat Centro",
"type": "web_widget"
}
],
"manager": {
"id": "4c8e2a6b-1d3f-4e5a-9b7c-0f2d4a6c8e14",
"name": "Ana Ejemplo"
},
"salespeople": [],
"notes_for_ai": "La entrada está frente a la plaza.",
"archived": false,
"created_at": "2026-11-06T16:00:00Z",
"updated_at": "2026-11-09T16:00:00Z"
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"has_more": false
}
}/v1/store/branchesAdd a store branch
Adds a branch as the Store page's editor does: its address and map pin, weekly hours, closed days, manager and salespeople, its own channels and its notes for the AI. It runs the Store page's own route as the member who created the key, so its rules hold: every check the editor gets, and a key created by an owner, admin or builder. Answers the branch as GET reads it.
store:writeTakes an Idempotency-KeyWorkspace keys only · acts as the key's creatorstore:write is given to a key only on its own: no preset, shortcut or default gives it, and keys made before it existed don't hold it.
Adding a branch never waits for approval, except with channel_ids: taking those channels from where they were (another branch, shared, or outside Store) is a change, so it waits for an owner's or admin's approval when the key's changes do (202 with data.change_request), as the same move through PATCH /v1/store/branches/{id} or PATCH /v1/store/channels/{id} does.
Request body
namestring · 1–80 charactersrequiredIts name, unique among the workspace's active branches (archiving one frees its name).
kindbranch | factory | warehouseThe kind of location; branch when left out.
addressstring | null · up to 200Street and number; null or blank clears it.
citystring | null · up to 120Its city: on a shared channel the AI asks the customer's city to find their branch. null or blank clears it.
postal_codestring | null · up to 10Letters, digits, spaces or dashes (2 to 10); null or blank clears it.
google_maps_urlstring | null · up to 2,000A Google Maps link (a short link is followed) or coordinates like 25.6866, -100.3161: its map pin, which the AI sends as the location on WhatsApp. null or blank removes the pin.
hoursobjectWeekly hours on the branch's clock (an IANA timezone in tz). Left out, it opens Monday to Friday 09:00–19:00 and Saturday 09:00–14:00 on the workspace's timezone.
hours.tzstringrequiredIANA timezone, e.g. America/Monterrey.
hours.daysobjectrequired0 = Sunday through 6 = Saturday; missing days are closed.
closuresobject[] · 0–100 itemsDays it is closed, at most one a day, from the workspace's yesterday on, as GET reads them (an earlier day isn't saved).
closures[].datestringrequiredYYYY-MM-DD on the branch's clock.
closures[].reasonstring | null · up to 80Why it is closed.
manager_iduuid | nullIts manager: a member of the workspace who can work tickets (owner, admin, builder or operator); null for none.
salespeople_idsuuid[] · 0–50 itemsIts salespeople, who take the branch's orders by turns: members who can work tickets, never its manager. The list replaces the one it has.
channel_idsuuid[] · 0–50 itemsIts own channels: a request on one of them is this branch's. The list replaces the one it has; a channel another branch had becomes this one's, and one left out becomes shared.
notes_for_aistring | null · up to 1,000What the AI should know about it (parking, how to find the entrance…); null or blank clears them.
Show 12 more fields
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorA manager or salesperson who isn't a member of the workspace who can work tickets, the manager also among the salespeople, a channel that isn't the workspace's, hours that aren't a timezone with windows like 09:00–19:00 (open before close, not overlapping), two closures on one day, or a Google Maps link that can't be read (details.reason maps_link_<reason>).409conflictAnother active branch has this name (details.reason branch_name_taken).403forbiddenThe member who created the key can't set Store up (only owners, admins and builders do), or the key lacks store:write.403forbiddenStore is not enabled for this workspace. NuTalk switches the module on per workspace (details.reason store_off).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/store/branches \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "Monterrey Centro",
"kind": "branch",
"address": "Calle Ejemplo 120",
"city": "Monterrey",
"postal_code": "64000",
"google_maps_url": "https://www.google.com/maps?q=25.67,-100.31",
"hours": {
"tz": "America/Monterrey",
"days": {
"1": [
[
"09:00",
"19:00"
]
],
"2": [
[
"09:00",
"19:00"
]
],
"3": [
[
"09:00",
"19:00"
]
],
"4": [
[
"09:00",
"19:00"
]
],
"5": [
[
"09:00",
"19:00"
]
],
"6": [
[
"09:00",
"14:00"
]
]
}
},
"closures": [
{
"date": "2026-12-25",
"reason": "Navidad"
}
],
"manager_id": "4c8e2a6b-1d3f-4e5a-9b7c-0f2d4a6c8e14",
"channel_ids": [
"9f19ef32-eaef-452c-bebc-14d9759cdb64"
],
"notes_for_ai": "La entrada está frente a la plaza."
}'{
"success": true,
"data": {
"id": "b6f9a520-1f1e-4c2a-9a55-2d6d3f1c9e30",
"name": "Monterrey Centro",
"kind": "branch",
"address": "Calle Ejemplo 120",
"city": "Monterrey",
"postal_code": "64000",
"map_pin": {
"latitude": 25.67,
"longitude": -100.31,
"google_maps_url": "https://www.google.com/maps?q=25.67,-100.31"
},
"hours": {
"tz": "America/Monterrey",
"days": {
"1": [
[
"09:00",
"19:00"
]
],
"2": [
[
"09:00",
"19:00"
]
]
}
},
"closures": [
{
"date": "2026-12-25",
"reason": "Navidad"
}
],
"open_now": true,
"closes_at": "19:00",
"channels": [
{
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Chat Centro",
"type": "web_widget"
}
],
"manager": {
"id": "4c8e2a6b-1d3f-4e5a-9b7c-0f2d4a6c8e14",
"name": "Ana Ejemplo"
},
"salespeople": [],
"notes_for_ai": "La entrada está frente a la plaza.",
"archived": false,
"created_at": "2026-11-06T16:00:00Z",
"updated_at": "2026-11-09T16:00:00Z"
}
}/v1/store/branches/:idGet a store branch
One branch of this workspace, including an archived one, with its hours, closures, own channels and people. A bad id or another workspace's branch answers 404 Branch not found.
store:readPath parameters
iduuidrequiredThe branch id.
Errors
404not_foundNo branch with this id in your workspace (ids of other workspaces answer the same).403forbiddenStore is not enabled for this workspace. NuTalk switches the module on per workspace (details.reason store_off).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/store/branches/b6f9a520-1f1e-4c2a-9a55-2d6d3f1c9e30 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "b6f9a520-1f1e-4c2a-9a55-2d6d3f1c9e30",
"name": "Monterrey Centro",
"kind": "branch",
"address": "Calle Ejemplo 120",
"city": "Monterrey",
"postal_code": "64000",
"map_pin": {
"latitude": 25.67,
"longitude": -100.31,
"google_maps_url": "https://www.google.com/maps?q=25.67,-100.31"
},
"hours": {
"tz": "America/Monterrey",
"days": {
"1": [
[
"09:00",
"19:00"
]
],
"2": [
[
"09:00",
"19:00"
]
]
}
},
"closures": [
{
"date": "2026-12-25",
"reason": "Navidad"
}
],
"open_now": true,
"closes_at": "19:00",
"channels": [
{
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Chat Centro",
"type": "web_widget"
}
],
"manager": {
"id": "4c8e2a6b-1d3f-4e5a-9b7c-0f2d4a6c8e14",
"name": "Ana Ejemplo"
},
"salespeople": [],
"notes_for_ai": "La entrada está frente a la plaza.",
"archived": false,
"created_at": "2026-11-06T16:00:00Z",
"updated_at": "2026-11-09T16:00:00Z"
}
}/v1/store/branches/:idChange or archive a store branch
Changes the fields sent, as the Store page's editor does; a field left out stays as it is. archived: true, sent alone, archives the branch: it leaves the lists and the AI's choices, its channels become shared and its requests keep it. It runs the Store page's own route as the member who created the key, so its rules hold: every check the editor gets, and a key created by an owner, admin or builder. Answers the branch as GET reads it.
store:writeCan wait for approvalWorkspace keys only · acts as the key's creatorWith a key whose changes wait for approval, a change answers 202 with data.change_request; archiving waits as a delete does.
store:write is given to a key only on its own: no preset, shortcut or default gives it, and keys made before it existed don't hold it.
Path parameters
iduuidrequiredThe branch id.
Request body
namestring · 1–80 charactersIts name, unique among the workspace's active branches (archiving one frees its name).
kindbranch | factory | warehouseThe kind of location.
addressstring | null · up to 200Street and number; null or blank clears it.
citystring | null · up to 120Its city: on a shared channel the AI asks the customer's city to find their branch. null or blank clears it.
postal_codestring | null · up to 10Letters, digits, spaces or dashes (2 to 10); null or blank clears it.
google_maps_urlstring | null · up to 2,000A Google Maps link (a short link is followed) or coordinates like 25.6866, -100.3161: its map pin, which the AI sends as the location on WhatsApp. null or blank removes the pin.
hoursobjectIts weekly hours, whole: they replace the ones it has.
hours.tzstringrequiredIANA timezone, e.g. America/Monterrey.
hours.daysobjectrequired0 = Sunday through 6 = Saturday; missing days are closed.
closuresobject[] · 0–100 itemsDays it is closed, at most one a day, from the workspace's yesterday on, as GET reads them (an earlier day isn't saved). The list replaces those the branch has; earlier ones stay.
closures[].datestringrequiredYYYY-MM-DD on the branch's clock.
closures[].reasonstring | null · up to 80Why it is closed.
manager_iduuid | nullIts manager: a member of the workspace who can work tickets (owner, admin, builder or operator); null for none. Sent without salespeople_ids, the salespeople stay.
salespeople_idsuuid[] · 0–50 itemsIts salespeople, who take the branch's orders by turns: members who can work tickets, never its manager. The list replaces the one it has. Sent without manager_id, the manager stays.
channel_idsuuid[] · 0–50 itemsIts own channels: a request on one of them is this branch's. The list replaces the one it has; a channel another branch had becomes this one's, and one left out becomes shared.
notes_for_aistring | null · up to 1,000What the AI should know about it (parking, how to find the entrance…); null or blank clears them.
archivedbooleanOnly true: archives the branch; send it alone. Archiving an archived branch changes nothing.
Show 13 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorA manager or salesperson who isn't a member of the workspace who can work tickets, the manager also among the salespeople, a channel that isn't the workspace's, hours that aren't a timezone with windows like 09:00–19:00 (open before close, not overlapping), two closures on one day, or a Google Maps link that can't be read (details.reason maps_link_<reason>).404not_foundNo branch with this id in your workspace (ids of other workspaces answer the same).409conflictAnother active branch has this name (details.reason branch_name_taken).409conflictThe branch is archived: it can't be changed (details.reason branch_archived).403forbiddenThe member who created the key can't set Store up (only owners, admins and builders do), or the key lacks store:write.403forbiddenStore is not enabled for this workspace. NuTalk switches the module on per workspace (details.reason store_off).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PATCH https://www.nutalk.ai/v1/store/branches/b6f9a520-1f1e-4c2a-9a55-2d6d3f1c9e30 \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"hours": {
"tz": "America/Monterrey",
"days": {
"1": [
[
"10:00",
"14:00"
],
[
"16:00",
"20:00"
]
],
"6": [
[
"10:00",
"14:00"
]
]
}
},
"notes_for_ai": "Estacionamiento gratis en el sótano."
}'{
"success": true,
"data": {
"id": "b6f9a520-1f1e-4c2a-9a55-2d6d3f1c9e30",
"name": "Monterrey Centro",
"kind": "branch",
"address": "Calle Ejemplo 120",
"city": "Monterrey",
"postal_code": "64000",
"map_pin": {
"latitude": 25.67,
"longitude": -100.31,
"google_maps_url": "https://www.google.com/maps?q=25.67,-100.31"
},
"hours": {
"tz": "America/Monterrey",
"days": {
"1": [
[
"09:00",
"19:00"
]
],
"2": [
[
"09:00",
"19:00"
]
]
}
},
"closures": [
{
"date": "2026-12-25",
"reason": "Navidad"
}
],
"open_now": true,
"closes_at": "19:00",
"channels": [
{
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "Chat Centro",
"type": "web_widget"
}
],
"manager": {
"id": "4c8e2a6b-1d3f-4e5a-9b7c-0f2d4a6c8e14",
"name": "Ana Ejemplo"
},
"salespeople": [],
"notes_for_ai": "La entrada está frente a la plaza.",
"archived": false,
"created_at": "2026-11-06T16:00:00Z",
"updated_at": "2026-11-09T16:00:00Z"
}
}/v1/store/channelsList channels' Store choice
The workspace's channels with their Store choice, as Store settings › Channels and branches shows them: a branch's own channels first, then the shared ones, then those outside Store. Each names its branch, the AI agent that answers it, and what a request that comes in there gets. PATCH /store/channels/{id} changes the choice (store:write).
store:readA channel linked to an archived branch reads as Store settings shows it: no longer that branch's. Channels of an AI PBX aren't listed.
Query parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
modebranch | shared | noneOnly a branch's own channels, the shared ones, or those outside Store.
branch_iduuidOnly this branch's own channels.
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).403forbiddenStore is not enabled for this workspace. NuTalk switches the module on per workspace (details.reason store_off).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/store/channels?mode=branch" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "WhatsApp Centro",
"type": "whatsapp",
"kind": "chat",
"mode": "branch",
"branch": {
"id": "6a0d4f81-2e5c-4b1d-a9f7-3c4d5e6f7a98",
"name": "Centro"
},
"agent": {
"name": "Elena",
"serves_branches": true
},
"requests": {
"branch": "channel",
"reason": null
}
}
],
"pagination": {
"total": 1,
"limit": 20,
"offset": 0,
"has_more": false
}
}/v1/store/channels/:idChange a channel's Store choice
Makes a channel a branch's own (mode: branch with branch_id), shared (the AI asks the customer's city and offers the nearest branch), or not a Store channel, as Store settings › Channels and branches does. It runs that screen's own route as the member who created the key, so its rules hold: a channel Store settings lists, an active branch of this workspace, and a key created by an owner, admin or builder. Answers the channel as GET /store/channels lists it.
store:writeCan wait for approvalWorkspace keys only · acts as the key's creatorstore:write is given to a key only on its own: no preset, shortcut or default gives it, and keys made before it existed don't hold it.
Moving a channel to another branch, to shared or out of Store changes where its new requests go from then on; requests already registered keep their branch.
Path parameters
iduuidrequiredThe channel id.
Request body
modebranch | shared | nonerequiredbranch: the branch's own channel. shared: the AI asks the city. none: not a Store channel.
branch_iduuid | nullThe branch, with mode: branch only: an active branch of this workspace.
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo channel with this id in your workspace (ids of other workspaces answer the same).404not_foundThe branch isn't an active branch of this workspace (Branch not found.).403forbiddenThe member who created the key can't set Store up (only owners, admins and builders do), or the key lacks store:write.403forbiddenStore is not enabled for this workspace. NuTalk switches the module on per workspace (details.reason store_off).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PATCH https://www.nutalk.ai/v1/store/channels/b6f9a520-1f1e-4c2a-9a55-2d6d3f1c9e30 \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "branch",
"branch_id": "6a0d4f81-2e5c-4b1d-a9f7-3c4d5e6f7a98"
}'{
"success": true,
"data": {
"id": "9f19ef32-eaef-452c-bebc-14d9759cdb64",
"name": "WhatsApp Centro",
"type": "whatsapp",
"kind": "chat",
"mode": "branch",
"branch": {
"id": "6a0d4f81-2e5c-4b1d-a9f7-3c4d5e6f7a98",
"name": "Centro"
},
"agent": {
"name": "Elena",
"serves_branches": true
},
"requests": {
"branch": "channel",
"reason": null
}
}
}