canonical: https://jentic.com/apis/ouropal.com/opal

# Ouropal Opal API

Opal is a content planning and collaboration platform for creative teams, social media managers, and marketing agencies. The v3 API (work in progress) follows the JSON:API specification and provides programmatic access to boards, moments (content items), content schedules, collaborators, and custom fields. Opal helps teams plan, organize, and collaborate on content calendars with visual boards, deadlines, and team workflows. Note: The v2 API is more complete in some areas; this is the v3 iteration.

## For AI agents

Manage content planning with Opal: access boards, moments, content schedules, collaborators, and custom fields for content calendar and creative workflow management.

## Scope

Does not publish content, manage media assets, or handle social media posting - use only for content planning, calendar management, and team collaboration workflows.

## Capabilities

- Retrieve and manage boards for organizing content by project, campaign, or theme
- Access moments (content items) with metadata, schedules, and assignments
- List and manage content schedules for planning publication dates
- Manage board collaborators and team permissions
- Access and configure custom fields for extending board and moment metadata
- List board objects including content pieces, assets, and planning items
- Organize content calendars with visual planning and deadlines
- Collaborate on content workflows with team members

## Use cases

### Social Media Content Calendar Integration

Social media managers can integrate Opal boards with publishing tools to automate content workflows. GET `/api/v3/boards` retrieves content boards, GET `/api/v3/moments` lists scheduled content items, and collaborator endpoints manage team assignments. Agents can pull scheduled posts from Opal, sync with publishing platforms like Buffer or Hootsuite, and update status in both systems.

Example prompt: GET `/api/v3/boards` to list content boards, then GET `/api/v3/moments` filtered by date range to retrieve scheduled social media posts for publication automation.

### Marketing Campaign Planning Dashboards

Marketing teams can build custom dashboards that aggregate content planning data from Opal. GET `/api/v3/boards/{board_id}/objects` retrieves all content items in a campaign board, and GET `/api/v3/boards/{board_id}/collaborators` shows team assignments. This enables executive views of campaign status, content pipeline, and team workload without manual reporting.

Example prompt: GET `/api/v3/boards` to list campaign boards, then GET `/api/v3/boards/{board_id}/objects` for each board to aggregate content status and build dashboard views.

### Agency Client Content Reporting

Marketing agencies managing multiple client content calendars can generate automated reports. GET `/api/v3/boards` with client filters lists client boards, and GET `/api/v3/moments` retrieves scheduled content by client. Agents can produce weekly or monthly content summaries, track deliverables against contracts, and provide transparency to clients without manual spreadsheet updates.

Example prompt: GET `/api/v3/boards` filtered by client, then GET `/api/v3/moments` for each board to generate client-specific content reports with scheduled and completed items.

### Content Workflow Automation

Teams can automate content approval workflows by integrating Opal with task management and approval tools. GET `/api/v3/moments` retrieves content items, custom fields track approval status, and collaborator data shows reviewers. Agents can trigger notifications when content reaches review stages, route to approvers, and update status after approval without manual coordination.

Example prompt: GET `/api/v3/moments` to find content items in review stage, then use custom fields and collaborators to route approval requests and update status after review.

### AI Agent for Content Planning Operations

Let an AI agent handle content planning tasks for a marketing team - retrieving scheduled content, checking team assignments, and generating content reports. Through Jentic, the agent loads only the required operations and Opal OAuth tokens are injected at execution time.

Example prompt: Use the Jentic search query 'list opal content boards' to find GET `/api/v3/boards`, load its schema, and execute to retrieve content boards for planning analysis.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/api/v3/boards` | List all content boards |
| GET | `/api/v3/boards/{board_id}` | Get a specific board with details |
| GET | `/api/v3/boards/{board_id}/objects` | List all objects (content items) in a board |
| GET | `/api/v3/boards/{board_id}/collaborators` | List board collaborators and permissions |
| GET | `/api/v3/moments` | List content moments with schedules |
| GET | `/api/v3/moments/{moment_id}` | Get a specific moment's details |

## Key resources

- **Boards** — Content planning boards for organizing projects, campaigns, or themes
- **Moments** — Content items with metadata, schedules, assignments, and status tracking
- **Content Schedules** — Publication dates and deadlines for planned content
- **Collaborators** — Team members with permissions and assignments on boards
- **Custom Fields** — Extensible metadata for boards and moments including approval status, content type, and tags
- **Board Objects** — All content items, assets, and planning elements within a board

## Why Jentic

- **Setup:** Wiring the Opal API by hand means running its OAuth 2.0 authorization code flow against login.ouropal.com, handling token refresh, and managing your own retries across board and moment reads. Through Jentic you install once, import the Opal API from the API Directory, store the OAuth credentials once, and your agent calls it.
- **Permission scoping:** Opal puts the board id in the URL path (`/api/v3/boards/{board_id}/...`), so a rule can pin your agent to one board: it can read that board's objects and collaborators. You choose the operations it may call, and since this surface is read-only, an agent can review planning content without changing it.
- **Credential handling:** Your Opal OAuth credentials are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list content boards' or 'read the moments planned on a board', and Jentic returns the matching Opal operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Airtable API** — Flexible database and content planning alternative with custom workflows.
- **Asana API** — Project management that complements Opal's content planning.
- **Trello API** — Board-based project management alternative to Opal.

## FAQ

### What authentication does the Opal API use?

The Opal API uses OAuth2 authentication. Users must authorize your application to access their Opal data through the OAuth flow. Access tokens are included in requests. Through Jentic, tokens are managed securely and injected at execution time.

### What is the difference between v2 and v3 of the Opal API?

The v3 API follows the JSON:API specification for better standardization and consistency. However, v2 is more complete in some areas as v3 is still a work in progress. Choose v3 for new integrations and JSON:API compatibility.

### What are moments in Opal?

Moments are individual content items within a board - social posts, blog articles, videos, or any planned content piece. Each moment has metadata like schedules, assignments, custom fields, and status.

### Can I create or update content through the API?

The v3 API currently focuses on retrieval endpoints (GET). Creation and update operations may be available in v2 or will be added to v3 as it matures. Check the API documentation for the latest capabilities.

### How do I organize content by client or campaign?

Use boards to organize content by client, campaign, or project. Each board can have its own collaborators, custom fields, and content items (moments). List boards with GET `/api/v3/boards` to access organizational structure.

### What are custom fields used for?

Custom fields extend boards and moments with additional metadata like approval status, content type, priority, tags, or client-specific attributes. They enable flexible content planning workflows beyond standard fields.

### Can I limit what my agent is allowed to do with the Opal API?

Yes. Because you run Jentic One yourself, your own rules decide which Opal operations and OAuth credentials the agent may use. Since Opal puts the board id in the URL path, such as `/api/v3/boards/{board_id}/objects` and `/api/v3/boards/{board_id}/collaborators`, you can pin the agent to a single board and let it read only that board's objects and collaborators. This surface is read-only, so the agent can review planning content, moments, and schedules without changing them.