Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.copera.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Introduction

Welcome! This guide will walk you through the essentials of getting started with the Copera Public API. Whether you’re building a bot, workflow automation, or a custom integration, this page helps you understand the setup process and the first steps required to interact with Copera programmatically.

​
Prerequisites

Before using the Public API, ensure the following:
  • You have access to a workspace eligible for integrations.
  • You have the required user permissions to create and manage integrations.
  • You understand the basic structure of Copera resources (Boards, Tables, Channels, Documents).
For permission details, see the Integration Permissions page.

​
Step 1: Create an Integration

To use the Public API, you need an API key linked to an integration.
  1. Open your Workspace Settings.
  2. Navigate to Integrations.
  3. Click Create new API key.
  4. Give your integration a name.
  5. Assign a bot name (this becomes the integration’s identity in channels).
  6. Choose the required permissions.
  7. Copy the API key immediately — it appears only once.
For a detailed walkthrough, see the Integration Creation page.

​
Step 2: Assign Permissions

Integrations operate under explicit permissions to ensure workspace security. Common permissions include:
  • ACCESS_CHANNELS — required to send messages in text channels.
  • ACCESS_BOARDS — required to list and interact with boards.
Integrations must also be added as participants of specific channels or boards to access them. Personal Access Tokens (PATs) can also be used to access documents without needing explicit permissions — the token inherits the authenticated user’s access. See Integration Permissions and Board Access for specifics.

​
Step 3: Make Your First API Request

Once your integration is created and permissions are set:

​
Example: Send a Message

Send a text message to a channel: 
POST https://api.copera.ai/public/v1/chat/send-message
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

{
  "channel": "<channelId>",
  "message": "Hello from my integration!"
}
If the integration is a participant in the channel and has the correct permissions, the message will appear instantly.

​
Step 4: Explore Core Resources

The Public API provides access to essential workspace data:

​
Text Channels

  • Send formatted text messages.
  • Use Markdown and color tags.
  • Rate limited at 100 requests/min.
See Text Messages.

​
Boards

  • List boards you have access to.
  • Retrieve tables and rows.
  • Create new rows programmatically.
See How a Board Works and Board Access.

​
Documents

  • Create, update, and manage documents programmatically.
  • Read and write document content as Markdown.
  • Search across your documents with full-text search.
  • Requires a Personal Access Token (cp_pat_).
See How Documents Work.

​
Rate Limits

All endpoints enforce per‑minute limits. See Rate Limits for details.

​
Step 5: Handle Errors Gracefully

You should expect and handle API errors using:
  • HTTP status codes
  • Standard error structure { error, code }
Common cases:
  • Invalid IDs → 400
  • Missing permissions → 403
  • Exceeded rate limits → 429
See Error Handling for complete details.

​
Best Practices

  • Store API keys securely — never commit them to source control.
  • Validate your input before sending requests.
  • Use retries with backoff for rate limits.
  • Keep permissions scoped to the minimum required.
  • Leverage Developer Mode (when available) to quickly copy resource IDs.

​
Summary

  • Create an integration and generate an API key.
  • Assign permissions and add the integration to required channels or boards.
  • Start making API calls such as sending messages or interacting with boards.
  • Use personal access tokens to manage documents via the API.
  • Follow rate limits and handle errors correctly.
  • Explore the rest of this documentation for deeper functionality.