Authentication
1 endpoint
Block
6 endpoints
Channel
7 endpoints
Comment
1 endpoint
Connection
4 endpoints
Group
3 endpoints
Search
1 endpoint
System
3 endpoints
User
5 endpoints

The Are.na REST API provides programmatic access to the Are.na platform - a tool for connecting ideas and building knowledge together.

⚠️ Work in Progress: This v3 API is under active development. Breaking changes may occur. For production use, consider the stable v2 API.

Getting Started

All API requests use https://api.are.na as the base URL. Responses are JSON with consistent structure including hypermedia links for resource discovery.

Authentication

Most endpoints work without authentication but provide additional access when authenticated. Use the standard Authorization header:

Authorization: Bearer YOUR_TOKEN

Supported Token Types:

For OAuth2, note that the authorization endpoint is hosted on the main site (www.are.na/oauth/authorize), while the token endpoint is on the API (api.are.na/v3/oauth/token).

Authentication Levels:

  • Public: No authentication needed (e.g., /v3/ping)
  • Optional: Works unauthenticated but respects permissions when authenticated
  • Required: Returns 401 Unauthorized without valid token (e.g., /v3/me)

Rate Limiting

Acceptable Use: This API is intended for building applications that integrate with Are.na, not for scraping or bulk data collection. Automated crawling, systematic downloading of content, or any form of structured data harvesting is prohibited. If you need bulk access to data for research or other purposes, please contact us to discuss your use case.

Rate limits are enforced per-minute based on your tier:

Tier Requests/Minute
Guest (unauthenticated) 30
Free 120
Premium 300
Supporter/Lifetime 600

Rate Limit Headers (included in every response):

  • X-RateLimit-Limit: Your tier's per-minute limit
  • X-RateLimit-Tier: Current tier (guest/free/premium/supporter)
  • X-RateLimit-Window: Time window in seconds (always 60)
  • X-RateLimit-Reset: Unix timestamp when the limit resets

When you exceed limits, you'll receive a 429 Too Many Requests response with upgrade recommendations and retry timing.

Request Validation

All parameters are validated against this OpenAPI specification. Invalid requests return 400 Bad Request with detailed error messages.

Error Responses

Errors use standard HTTP status codes with JSON bodies:

{
  "error": "Not Found",
  "code": 404,
  "details": {
    "message": "The resource you requested does not exist"
  }
}

Common status codes:

  • 400: Invalid request parameters
  • 401: Authentication required or invalid
  • 403: Insufficient permissions
  • 404: Resource not found
  • 429: Rate limit exceeded
    Log in
    Sign up