Getting Started

Technical reference for the AltIndex REST API. For a quick start, see Getting Started.

Base URL

All API V2 requests use the following base URL:

https://v2.api.altindex.com

Authentication

All API requests (except the root endpoint) require authentication via an API key passed in the X-API-Key header.

Request Header

Include your API key in every request:

X-API-Key: your_api_key_here

API Key Format

API keys use a v2_ prefix.

Obtaining an API Key

Pro subscribers can create API keys at app.altindex.com/settings (opens in a new tab). Enterprise clients receive custom keys during onboarding.

API Key Scopes

API keys can be scoped to limit access to specific endpoints. This enables you to create keys with minimal permissions for different use cases (e.g., a key that only accesses social data).

Scope Format

Scopes follow the pattern category:action:

Wildcard Scopes

Use wildcards for broader access:

Example Scope Configurations

Social-only key (for social media dashboards):

["social:*"]

X and Instagram only:

["social:x", "social:instagram"]

Entity discovery + specific platforms:

["entities:*", "social:x", "social:reddit"]

Insufficient Scope Error

If your API key doesn't have the required scope, you'll receive a 403 Forbidden response:

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "API key does not have access to this endpoint. Required scope: social:x",
    "request_id": "req_abc123..."
  }
}

Rate Limiting

Rate limits are enforced on a 24-hour rolling window (not a calendar day reset).

Rate Limit Tiers

Pro keys are created at app.altindex.com/settings (opens in a new tab). For Enterprise access, contact sales (opens in a new tab).

Rate Limit Exceeded

When you exceed your limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily request limit exceeded.",
    "request_id": "req_abc123..."
  }
}

Best Practices

• Cache responses when possible
• Use date range filters to reduce data transfer
• Monitor your usage to avoid hitting limits

Error Handling

All errors follow a consistent JSON format with a unique request_id for troubleshooting. Each API Reference page also lists the specific error codes that endpoint can return.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "request_id": "req_<uuid>"
  }
}

Error Codes

OpenAPI Specification

Download the machine-readable spec: /openapi/v2.json

Next Steps

• Browse the Reference for endpoint details
• Connect AltIndex to your AI assistant via MCP
• Explore the Data Dictionary for field definitions and coverage