Getting Started

These docs describe the resources and endpoints that make up the Oktopost API. You can use the API to integrate Oktopost with your existing tools, automate workflows, and build custom applications on top of your social media data. If you have questions or need assistance, please contact our support team.

Authentication

All API requests must be authenticated using Basic HTTP Authentication. Authentication requires your Account ID as the username and your API Key as the password. You can find both values in the My Profile section of your Oktopost account.

API requests are subject to the same permissions as the user associated with the credentials. If you lack permissions to perform an action, the API returns a 403 (Forbidden) response. If you don't have access to a specific resource, the API returns a 404 (Not Found) response.

Base URL

The API's base URL depends on the data center your account is hosted on. If your account is hosted on the US data center, your base URL should be:

https://api.oktopost.com/v2

And if your account is hosted on the EU data center, your base URL should be:

https://eu-api.oktopost.com/v2

Verifying Authentication

Use the Me endpoint to verify your authentication and retrieve details about your account:

curl -u ACCOUNT_ID:API_KEY https://api.oktopost.com/v2/me

Response:

{
  "Result": true,
  "User": {
    "Id": "00A000000000000",
    "Name": "John Smith",
    "Email": "john@example.com",
    "LastLogin": "2020-10-27 08:27:30"
  },
  "Account": {
    "Id": "001000000000001",
    "Name": "Acme"
  }
}

It's a good practice to call this endpoint when initializing your integration to validate your setup before making other API requests.

Data Format

The API uses JSON for all request and response payloads, making it easy to work with in any modern programming language. All timestamps are represented as Unix timestamps (UTC EPOCH) — the number of seconds since January 1st, 1970 in the UTC timezone. This ensures consistent date and time handling across different systems and timezones. When sending data to the API, use the same timestamp format for any date or time fields.

Pagination

List endpoints support pagination to help you navigate large result sets. All API endpoints that return lists of objects share a common structure and accept standard pagination parameters. You can control the number of items returned per page, navigate between pages, and specify the sort order of results.

Pagination Parameters

Example Request

curl -u ACCOUNT_ID:API_KEY \
  "https://api.oktopost.com/v2/campaign?_count=100&_page=1&_order=created,0"

Example Response

{
    "Result": true,
    "Items": [...],
    "Total": 1024
}

Rate Limits

The API enforces rate limits to ensure stable performance for all users. Each user has a daily limit of 20,000 API calls, which resets at midnight UTC. Burst rates allow up to 60 calls per minute and 120 calls per 5-second window to accommodate short spikes in activity.

If you exceed the burst limit, your access will be temporarily blocked for 15 minutes. Plan your integration to stay within these limits by implementing appropriate request throttling and caching strategies.

Error Handling

Responses use conventional HTTP status codes to indicate success or failure. Response codes in the 2xx range indicate successful requests. Codes in the 4xx range indicate client errors that result from invalid or missing parameters, authentication issues, or malformed requests. Codes in the 5xx range indicate server errors on Oktopost's side.

Every API response contains a Result parameter which indicates if the request was successful. In case an error was captured, an Errors parameter will be returned as well:

{  
    "Result": false,
    "Errors": {  
        "API": {  
            "Error": "The page you are looking for was not found"
        }
    }
}

HTTP Status Codes