Getting Started With the OSCOM API: Authentication, Endpoints, and Common Use Cases

OSCOM's web interface covers the most common workflows for content production, analytics, SEO optimization, and campaign management. But the interface represents a curated set of capabilities, and the underlying platform is significantly more flexible than what the UI exposes. The OSCOM API gives you programmatic access to every module, every data source, and every action available in the platform. You can build custom integrations with tools OSCOM does not natively connect to, automate workflows that go beyond the built-in automation builder, pull data into your own data warehouse or BI tools, embed OSCOM capabilities into your own applications, and create custom reporting that combines OSCOM data with data from other systems. This guide covers everything you need to start building with the OSCOM API: authentication, core concepts, key endpoints, rate limits, error handling, and five practical use cases with code examples.

A note on who this guide is for: you do not need to be a software engineer to use the API, but you do need basic familiarity with making HTTP requests, reading JSON responses, and working with API keys. If you have ever used the APIs for tools like HubSpot, Stripe, or Slack, you will find the OSCOM API structure familiar. If APIs are entirely new to you, consider starting with a tool like Postman or Insomnia, which provide visual interfaces for making API requests without writing code. We will include curl examples throughout this guide that you can copy and run from any terminal.

Authentication: API Keys and Scoped Permissions

Every API request must include a valid API key in the Authorization header. API keys are created in the OSCOM dashboard under Settings, then API, then "Create New Key." When creating a key, you name it (for identification in audit logs), select the permission scopes it should have, and optionally set an expiration date.

Permission scopes. API keys use scoped permissions that control which endpoints the key can access and what actions it can perform. Available scopes include: content:read (read content assets, briefs, and templates), content:write (create, update, and publish content), analytics:read (query analytics data and dashboards), seo:read (read keyword data, rankings, and SEO recommendations), seo:write (create and update SEO configurations), campaigns:read (read campaign data and performance), campaigns:write (create and manage campaigns), contacts:read (read contact profiles and engagement data), contacts:write (create and update contact records), and admin (full access to all endpoints including workspace settings). We strongly recommend creating keys with the minimum required scopes for each integration. A reporting integration only needs read scopes. A CRM sync might need contacts:read and contacts:write but not content or campaign scopes.

Including the key in requests. Include the API key in the Authorization header using the Bearer scheme. A curl example looks like this: curl -H "Authorization: Bearer oscom_sk_your_key_here" https://api.oscom.ai/v1/analytics/overview. The key prefix (oscom_sk_) identifies it as an OSCOM secret key. Never expose API keys in client-side code, public repositories, or browser requests. They should only be used in server-side code or secure automation tools.

Key rotation. API keys do not expire by default, but you can set an expiration date during creation or update it later. For production integrations, we recommend rotating keys every 90 days. The rotation process is: create a new key with the same scopes, update your integration to use the new key, verify the integration works with the new key, then delete the old key. OSCOM supports having multiple active keys simultaneously, so there is no downtime during rotation.

Core Concepts: Resources, Endpoints, and Pagination

The OSCOM API is organized around resources that map to the platform's modules. Each resource has a base URL, supports standard CRUD operations (create, read, update, delete), and returns JSON responses with a consistent structure. The base URL for all API requests is https://api.oscom.ai/v1/. All endpoints use this base followed by the resource path.

Resource structure. The primary resources are: /content (content assets including blog posts, social posts, emails, and derivatives), /content/briefs (content briefs and templates), /content/voice (voice profiles and training data), /analytics (analytics data, dashboards, and reports), /analytics/events (raw event data), /seo (keyword data, rankings, and recommendations), /seo/pages (page-level SEO data), /campaigns (campaign management and performance), /contacts (contact profiles with engagement data), /contacts/segments (audience segments), and /webhooks (webhook subscriptions for event notifications). Each resource supports GET (retrieve), POST (create), PUT (update), PATCH (partial update), and DELETE (remove) methods as appropriate. List endpoints (like GET /content) return paginated results. Detail endpoints (like GET /content/abc123) return a single resource.

Response structure. Every API response follows a consistent envelope structure. Successful responses include a "data" field containing the requested resource or array of resources, a "meta" field with metadata like pagination information and request ID, and an "included" field for related resources when using the expand parameter. Error responses include an "error" field with a code, message, and details array. The consistent structure means you can write generic response handling code that works across all endpoints.

Pagination. List endpoints return a maximum of 50 items per page by default (configurable up to 100 with the limit query parameter). Pagination uses cursor-based navigation: each response includes a "next_cursor" value in the meta field. To retrieve the next page, include cursor=value_from_next_cursor as a query parameter. When next_cursor is null, you have reached the last page. Cursor-based pagination is more reliable than offset-based pagination because it handles records being added or removed between page requests without skipping or duplicating items.

Filtering and sorting. List endpoints support filtering via query parameters. Each resource has its own set of filterable fields documented in the API reference. Common filters include date ranges (created_after, created_before), status (status=published, status=draft), and type-specific filters (channel=linkedin for content, position_lte=10 for SEO keywords). Sorting uses the sort parameter with a field name and optional direction: sort=created_at for ascending or sort=-created_at for descending (note the minus prefix for descending).

Key Endpoints by Module

This section covers the most frequently used endpoints in each module. The full API reference with all endpoints, parameters, and response schemas is available at docs.oscom.ai/api, but these are the ones you will use in ninety percent of integrations.

Content module. GET /content returns a list of content assets with filters for type (blog, social, email, derivative), status (draft, review, published, archived), and date range. POST /content/briefs creates a new content brief; the request body includes the topic, angle, target audience, target channels, and key messages. POST /content/briefs/{id}/generate triggers draft generation from an existing brief and returns a job ID since generation is asynchronous. GET /content/jobs/{id} checks the status of an async generation job and returns the generated content when complete. PUT /content/{id} updates an existing content asset, commonly used to push edits from an external editor back into OSCOM.

Analytics module. GET /analytics/overview returns a summary of key metrics for a date range, including sessions, page views, conversions, and revenue. GET /analytics/events returns raw event data with filters for event type, user, date range, and properties. This endpoint is useful for pulling OSCOM engagement data into your own analytics warehouse. GET /analytics/reports/{id} returns a specific dashboard or report's data in JSON format, which you can feed into custom visualizations. POST /analytics/query runs a custom analytics query using OSCOM's query language (similar to SQL but optimized for event data). This is the most flexible analytics endpoint and supports aggregations, grouping, filtering, and time-series decomposition.

SEO module. GET /seo/keywords returns your tracked keywords with current position, search volume, clicks, impressions, and CTR. GET /seo/pages returns page-level SEO data including keyword associations, rankings, and optimization scores. GET /seo/recommendations returns the current SEO recommendations generated by OSCOM's analysis engine, sorted by estimated impact. POST /seo/keywords adds new keywords to tracking. These endpoints are commonly used to build custom SEO dashboards, feed keyword data into external tools, or create automated reporting that combines SEO data with other marketing metrics.

Contacts module. GET /contacts returns contact profiles with engagement data, filterable by segment, engagement score range, last activity date, and custom properties. GET /contacts/{id}/timeline returns the engagement timeline for a specific contact, showing every tracked interaction in chronological order. POST /contacts creates or updates a contact (upsert by email address). POST /contacts/segments creates a new contact segment based on filter criteria. The contacts module is the primary integration point for CRM sync, allowing you to push OSCOM engagement data into your CRM and pull CRM lifecycle data into OSCOM.

Rate Limits and Error Handling

The API enforces rate limits to ensure fair usage and platform stability. Standard plans allow 100 requests per minute per API key. Enterprise plans allow 500 requests per minute. Rate limits are applied per key, not per workspace, so if you have multiple integrations each with their own key, each key gets its own limit.

Rate limit headers are included in every response: X-RateLimit-Limit (your maximum requests per minute), X-RateLimit-Remaining (requests remaining in the current window), and X-RateLimit-Reset (Unix timestamp when the current window resets). When you exceed the rate limit, the API returns a 429 Too Many Requests response with a Retry-After header indicating how many seconds to wait before retrying.

Best practices for rate limiting. Implement exponential backoff for retries: wait one second after the first 429, two seconds after the second, four seconds after the third, and so on up to a maximum of thirty seconds. Use batch endpoints when available: POST /contacts/batch accepts up to 100 contacts in a single request, which is one hundred times more efficient than individual POST /contacts calls. Cache responses for data that changes infrequently: keyword rankings update daily, so caching SEO data for an hour eliminates unnecessary requests. Monitor your rate limit headers and alert yourself when X-RateLimit-Remaining drops below 20% consistently, which signals that your integration needs optimization before it starts hitting limits.

Error responses. The API uses standard HTTP status codes. 200 indicates success. 201 indicates resource created. 204 indicates successful deletion with no content. 400 indicates a bad request with invalid parameters (check the error details for which parameter is wrong). 401 indicates authentication failure (invalid or expired API key). 403 indicates authorization failure (valid key but insufficient scopes). 404 indicates resource not found. 422 indicates unprocessable entity (valid syntax but semantic errors, like trying to publish content that is still in draft status without required fields). 429 indicates rate limit exceeded. 500 indicates an internal server error (these are rare and automatically logged for investigation). Every error response includes a request_id field that you can reference when contacting support.

Use Case 1: Custom CRM Sync

The most common API use case is syncing OSCOM engagement data with a CRM that does not have a native integration. While OSCOM offers native integrations for HubSpot and Salesforce, teams using other CRMs (Pipedrive, Close, Copper, or custom CRMs) can build a sync using the API.

The sync has two directions. OSCOM to CRM: pull contact engagement data from GET /contacts and push it to your CRM's API. The key data points to sync are the engagement score, last content interaction, content topics of interest, campaign participation, and attribution path. CRM to OSCOM: pull deal and lifecycle data from your CRM and push it to POST /contacts in OSCOM, updating lifecycle stage, deal value, and CRM-specific properties. The bidirectional sync ensures both systems have the context they need: your CRM has engagement intelligence for sales conversations, and OSCOM has lifecycle context for marketing segmentation and campaign targeting.

A typical sync runs on a scheduled cadence. Every fifteen minutes, your sync script pulls recently updated contacts from OSCOM (using the updated_after filter), transforms the data to match your CRM's field structure, and pushes it via the CRM's API. Then it pulls recently updated records from your CRM, transforms the data to match OSCOM's contact schema, and pushes it via POST /contacts/batch. The entire cycle for a database of ten thousand contacts typically processes in under thirty seconds and uses fewer than fifty API requests per cycle, well within rate limits.

Use Case 2: Custom Reporting Pipeline

Teams with data warehouses (Snowflake, BigQuery, Redshift) often want to pull OSCOM data into their warehouse for custom analysis alongside data from other business systems. The API makes this straightforward with the analytics query endpoint and event export capabilities.

The recommended approach is an incremental export pipeline. On an hourly or daily schedule, your pipeline script calls GET /analytics/events with the created_after parameter set to the timestamp of the last successful export. This returns only new events since the last run, keeping the data volume manageable and the API usage efficient. The events are written to your warehouse's staging table, then merged into the production analytics tables via your warehouse's ETL process.

The event data model includes the event type (page_view, content_read, form_submit, email_click, campaign_interaction), timestamp, anonymous visitor ID, identified contact ID (if known), session ID, properties (event-specific key-value pairs like page URL, content title, campaign name), and UTM parameters. This granular event data supports any analytical query you can construct in SQL, from basic traffic reporting to advanced cohort analysis and attribution modeling.

For teams that want aggregated data rather than raw events, the POST /analytics/query endpoint accepts query definitions that specify metrics, dimensions, filters, and date ranges. The response returns pre-aggregated results that are more compact than raw events and easier to work with for standard reporting. A query like "sessions by channel for the last 30 days" returns a concise table instead of thousands of individual session events.

Use Case 3: Content Automation Beyond Built-In Workflows

OSCOM's built-in workflow automation covers common content production triggers, but the API enables automation scenarios that the UI does not support. For example: triggering content creation from external events, integrating with project management tools for editorial workflows, or building custom approval processes that span multiple systems.

An external trigger example: your customer success team logs a common customer question in your support ticketing system. An automation script monitors the support system for frequently asked questions (questions asked by more than five customers in a month). When a new FAQ emerges, the script creates an OSCOM content brief via POST /content/briefs with the topic set to the FAQ, the angle set to "customer education," and the template set to your "How-To Tutorial" template. The content team receives the brief in their review queue, adds context and depth, and produces a knowledge base article that preemptively answers the question for future customers.

A project management integration example: your editorial calendar lives in Asana or Monday.com. When a content task reaches the "Ready for Draft" status in your project management tool, a webhook triggers an automation script that creates a content brief in OSCOM via the API, pre-populated with the task's description and metadata. When the OSCOM content is approved and published (detected via webhook), the script updates the project management task to "Published" and adds the published URL. This keeps your editorial project management and your content production system in sync without manual status updates.

Use Case 4: Webhook Integrations for Real-Time Events

Webhooks are the inverse of API requests. Instead of your code calling the OSCOM API, OSCOM calls your code when specific events happen. This enables real-time integrations without polling. You register a webhook endpoint (a URL on your server that accepts POST requests) and subscribe it to specific event types.

Available webhook events include: content.published (a content asset was published), content.brief.created (a new brief was created, useful for notifying the team), contact.identified (an anonymous visitor was identified, useful for real-time lead alerts), contact.score.changed (a contact's engagement score crossed a threshold), campaign.completed (a campaign reached its end date), seo.ranking.changed (a tracked keyword moved by more than three positions), and analytics.alert.triggered (a dashboard alert threshold was crossed).

To register a webhook, POST to /webhooks with the URL, the list of event types to subscribe to, and an optional secret for request signing. OSCOM signs each webhook payload with HMAC-SHA256 using your secret, and includes the signature in the X-OSCOM-Signature header. Your endpoint should verify the signature before processing the payload to ensure the request genuinely came from OSCOM.

A practical webhook example: subscribe to contact.score.changed events with a threshold of score greater than 80. When a contact crosses this engagement threshold, your webhook endpoint receives a payload with the contact's email, new score, and recent activity summary. Your endpoint forwards this to a Slack channel where your sales team monitors hot leads. The sales rep sees the notification, checks the contact's timeline in their CRM, and reaches out while the interest is fresh. This entire flow happens in seconds after the score change, with zero polling or manual monitoring.

Use Case 5: Embedded Analytics

For agencies or consultancies that serve multiple clients, the API enables embedding OSCOM analytics into your own client-facing dashboards or portals. Instead of giving each client an OSCOM login, you pull the relevant data via the API and display it in your own branded interface.

The embedded analytics flow works as follows. Your client portal makes server-side API requests to OSCOM using the client's workspace credentials (each client workspace has its own API key). The API returns analytics data in JSON format, which your portal renders using your own visualization components. This approach gives you full control over the presentation, branding, and data combination. You can combine OSCOM data with data from other tools you use for the client, creating a unified performance view that no single tool provides on its own.

The POST /analytics/query endpoint is particularly useful for embedded analytics because it lets you define the exact metrics, dimensions, and filters for each dashboard widget. A widget showing "Organic Traffic by Week" sends a query specifying sessions as the metric, week as the time dimension, and channel equals organic as the filter. The response is a clean data array ready for chart rendering. You can use any frontend charting library (Chart.js, Recharts, D3, or Highcharts) to visualize the data because it arrives as standard JSON data structures rather than pre-rendered charts.

For real-time embedded dashboards, combine the API query endpoint with websocket connections to webhook events. When OSCOM sends a webhook for a significant event (new content published, ranking change, engagement threshold crossed), your portal can update the relevant widget immediately without waiting for the next polling cycle. This creates a live dashboard experience that feels responsive and current.

The API is where OSCOM stops being a standalone tool and becomes a platform. Every workflow that is too specific for the UI, every integration with a tool you already use, every custom report that combines data across systems, and every embedded analytics view in your client portal becomes possible through the API. The investment in learning the API pays dividends across every integration you build, because the patterns (authentication, pagination, error handling, webhooks) are consistent across all endpoints and modules. Start with one integration, get comfortable with the patterns, and then expand to more complex use cases as your confidence grows. The API documentation at docs.oscom.ai/api includes interactive examples for every endpoint, so you can experiment directly in the browser before writing any code.