API
Use /api/v1 to manage saved NotiCord workflows from an agent or script. The owner creates the first API key after connecting Discord and Notion.
Create and use a key
- Open API in NotiCordSelect Create key and name it after the agent, script, or automation that will use it.
- Copy the key immediatelyNotiCord shows the full key only once. Store it in the secret store used by that agent or script.
- Send it as a bearer tokenUse the key in the
Authorizationheader for protected/api/v1requests.
Access: every plan includes the API while the subscription or trial has active service. Otherwise protected endpoints return 403 with SUBSCRIPTION_ACCESS_REQUIRED until the owner restores access.
For example, list saved notification rules:
curl https://app.noticord.com/api/v1/notification-rules \
-H "Authorization: Bearer ntc_your_key"
Limits
| Limit | Starter | Standard | Pro |
|---|---|---|---|
| Active API keys | 1 | 2 | 5 |
| Requests/minute | 60 | 120 | 300 |
| Requests/day | 2000 | 10000 | 50000 |
When a key reaches a limit: the API returns 429 with Retry-After and rate-limit headers. After a plan change, if too many keys remain active, only the oldest keys within the new limit can call the API until you revoke extras.
What you can manage
Setup stays in NotiCord: connect Discord and Notion, create or revoke API keys, and link members to Notion identities. The API does not connect accounts or proxy arbitrary Discord and Notion requests.
For a Discord panel button that opens a Create page command using Choose in Discord, include parentPage on that button's open_create_command action. It sets the parent page for everyone using the button. The OpenAPI schema lists the page fields.
Choose connected resources
Start with these discovery requests using the same API key:
GET /api/v1/notion/workspaceslists your subscription’s stored Notion connections. Use each connection’sidasnotionWorkspaceId. The separateworkspaceIdis Notion’s identity and cannot be used in its place.GET /api/v1/notion/databases?notionWorkspaceId=CONNECTION_IDlists sources for that connection. Use the same query parameter on database detail, page search, relation-page search and user-directory requests. Database and page results retain their connection ID.GET /api/v1/discord/guild-installationslists your connected servers and their channels, including channel type and permissions. Use an installation’sidasdiscordInstallationIdand select a channel from that installation. Use?purpose=panelsfor panel destinations and their permissions.GET /api/v1/discord/direct-message-recipientslists existing members who can be selected for notification or summary DMs. Use a recipient’saccountIdwithdestinationKind: "direct_message". Pending invitations are excluded; Discord privacy settings can still block delivery.
Names may be duplicated or missing. Select by the returned IDs, rather than treating a display name as an identifier. A stored Notion connection can have unavailable provider access; querying that connection reports the problem. A Discord installation with status: "bot_removed" has no usable channels.
Include notionWorkspaceId alongside sourceType when creating a notification rule, scheduled summary, create command or page list. Notion Automation triggers and actions use that same connection ID. On updates, omitting notionWorkspaceId preserves the saved workflow’s connection.
For a channel notification or summary, include both discordInstallationId and channelId. Panels use the selected channel ID; NotiCord resolves and checks its owning server when saving. Create-command private threads use a text channel in the server where the command is run; NotiCord checks that channel when creating the thread. Automation channel targets use the installation and channel IDs; fixed user targets use Discord user IDs from the selected server’s mention-target search, rather than DM accountId values.
For example, configure a rule for the second workspace and second server by selecting their returned IDs and using this source and destination fragment in the complete notification-rule request:
{
"sourceType": "all",
"notionWorkspaceId": "22222222-2222-4222-8222-222222222222",
"destinationKind": "channel",
"discordInstallationId": "11111111-1111-4111-8111-111111111111",
"channelId": "123456789012345678"
}
Use discordInstallationId as a query parameter on /discord/guild-install, /discord/guild-install/mention-targets and /discord/guild-install/notion-link-unfurls to select one server. The link-preview setting also accepts the installation ID in /discord/guild-install/{guildInstallId}/notion-link-unfurls.
With one connection, you can omit its scope on directory requests and new workflows. With several, an unscoped Notion request returns 409 with WORKSPACE_SCOPE_REQUIRED; an unscoped server request returns 409 with DISCORD_SCOPE_REQUIRED. Select an ID from the relevant discovery list and retry. Directory requests and notification, summary, create-command and page-list sources reject foreign or disconnected workspace connections. Server selection and channel/DM delivery destinations also reject foreign or disconnected IDs. Channel notifications, summaries and panels also check the destination’s server. Create-command thread channels are checked at execution, as described above.
Configure ordered Automation actions
Automation actions run in the order of the actions array. Give each action a unique id. A later action can use a result from an earlier action; it cannot use its own result or a later action's result. When reordering actions through the API, keep each result-producing action before the actions that use it.
For example, create a Discord thread with an action whose id is create-room, then send a message into it using this target:
{ "kind": "action", "actionId": "create-room" }
The producer must provide the right kind of result: a Notion page for a page target, or a Discord channel or thread for a conversation target. A thread-state action requires a thread. The complete create-and-send request is in the Automation API example.
Templates contain ordered segments. A literal segment uses kind: "text" and text. A variable segment uses kind: "variable" and a reference. This template includes the earlier thread's URL:
{
"segments": [
{ "kind": "text", "text": "Discussion: " },
{
"kind": "variable",
"reference": {
"kind": "action",
"actionId": "create-room",
"variableId": "discord.channel_or_thread_url"
}
}
]
}
| Earlier action result | Available template variables |
|---|---|
| Created Notion page | notion.page_title, notion.page_url |
| Created or reused Discord channel or thread | discord.channel_or_thread_name, discord.channel_or_thread_url, discord.viewer_url |
An event variable instead uses a reference such as { "kind": "trigger", "variableId": "notion.title" }. Available event variables depend on the selected event. Notion property variables use notion.property.<propertyId> and require a Notion database source.
The OpenAPI schemas describe supported trigger, action, target, filter, and template variants and their field limits. Enabling an Automation also checks event/action compatibility, earlier-result references, required configuration, and access to selected resources. A disabled configuration can retain incomplete setup; it must pass these checks before it can run.
If an action fails, later actions are skipped. Earlier side effects are not rolled back. Disabling or deleting the Automation stops future runs; it does not undo earlier actions.
What responses include
Check what actually happened
Saving or enabling a workflow confirms its configuration. It does not confirm that NotiCord sent a Discord message or completed a Notion action.
Use these read-only endpoints with the same API key:
| Workflow | Health endpoint | Outcome evidence |
|---|---|---|
| Notification rule | GET /api/v1/notification-rules/{id}/health |
Latest recorded delivery attempt, last retained successful delivery, pending count and next queued send time. |
| Scheduled summary | GET /api/v1/scheduled-summaries/{id}/health |
Latest run timestamp and outcome, latest recorded delivery attempt and last retained successful delivery. |
| Automation | GET /api/v1/automations/{id}/health |
Latest run, its completed action results and current action, and last retained successful run. |
Every health response includes the resource id, saved enabled state, pause state and reason, a recovery action when available, and current capacity. These reads use NotiCord's stored state and make no Notion or Discord requests. They remain available during a provider outage, subject to normal API-key and subscription access checks.
latestDeliveryrecords a delivery attempt. Checksuccess,errorMessageand anywarningMessage; a successful delivery can still have a warning.lastSuccessfulDeliveryremains separate when a newer attempt failed. The record includes its timestamp, event ID and Discord message ID when recorded.- Summary
lastRunOutcomedistinguishessent,no_resultsandfailed. Ano_resultsrun sent no message and can be newer than the latest delivery record.lastRunAtis an attempt timestamp, not delivery confirmation. - Automation
latestRun.statusdistinguishessuccess,failed,skippedandrunning. A failed run can contain successful earlier actions.runningmeans completion has not been recorded, including after interruption; it does not prove that a worker is still running. Check completed actions and provider outcomes before repeating uncertain writes. These reads do not retry or resume execution. resourceCapacitydescribes saved-resource creation capacity. Reaching it does not itself mean an existing workflow stopped.notificationQuotadescribes the current billing-window sending quota, including add-on capacity; it applies to notifications, summaries and automation message actions. Both returnused,limit,remainingandexhausted. A null limit or remaining value means there is no finite limit. API request limits remain separate in theX-RateLimit-*response headers.
Null delivery or run fields mean there is no retained record for that result. They do not prove the workflow never ran. Event and run retention, incomplete recording, and later provider-side changes limit this evidence. The health response does not check current provider permissions or whether a previously sent message still exists.
Panel list and detail reads include publication: the recorded publication timestamp, Discord message ID and published channel ID, or null when no publication identity is available. The publication channel can differ from the current draft's channelId. Keep draft, published and needs_update distinct, and read any warning returned by a publish request before treating publication as fully complete. Publication evidence does not prove a later button interaction succeeded.
Correct a failed request
A 400 response means the request or selected configuration needs correction. Invalid fields include an issues list with a path and message; a numeric path entry identifies an item in a list. For example, ["actions", 0, "kind"] points to the first action's kind. For Automation configuration errors, a path may identify the affected action or event when several fields need correction. The top-level error gives the first problem; inspect all returned issues before sending the request again.
A 500 response means NotiCord could not complete the request. It does not mean the submitted configuration was invalid. Check the resource before retrying a create request to avoid creating it twice.
The OpenAPI schemas describe request shapes and field constraints. Enabling a workflow also checks its configuration and access to the selected Notion and Discord resources. Quick-action dropdowns with actions require a label; page lists using is me filters require channel sharing to be off.
Keep keys safe
- Revoke keys you no longer use from the app API page. Revoked keys stop working immediately.
- Never put a key in Notion, Discord, source code, or client-side browser code.