Getting Started

This guide covers authentication, API key scopes, rate limiting, and error handling for the AltIndex API V2.

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 to distinguish them from legacy V1 keys.

Obtaining an API Key

API keys are issued on a per-client basis. Contact info@altindex.com to discuss your requirements and receive access.

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

Rate limits are tailored to each client's needs. Contact info@altindex.com to discuss your usage requirements.

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