Developers
Authentication
1 endpoint
Block
8 endpoints
Channel
7 endpoints
Comment
1 endpoint
Connection
4 endpoints
Group
3 endpoints
Search
1 endpoint
System
3 endpoints
Upload
1 endpoint
User
5 endpoints
Developers
API Documentation
View as Markdown(Compact)

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

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)

Scopes

OAuth2 tokens and personal access tokens support the following scopes:

Scope Description
read Read-only access (default) — write operations will return 403 Forbidden
write Full read and write access

Tokens default to read scope. Request write scope when creating a token or authorizing an OAuth2 application to enable write access. Read-only tokens can view all resources the user has access to but cannot create, update, or delete anything.

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

Pagination

List endpoints return paginated results. Use these query parameters:

  • page: Page number (default: 1)
  • per: Items per page (default: 24, max: 100)

Responses include a meta object with pagination info:

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total_pages": 5,
    "total_count": 120,
    "next_page": 2,
    "prev_page": null,
    "has_more_pages": true
  }
}

Best Practices

Are.na channels and users can contain thousands of items. The following guidelines will help you build responsive, well-behaved integrations.

Paginate, Don't Enumerate

Never try to load an entire channel or user's content in one pass. Use page and per parameters to fetch only the data you need right now. Check meta.has_more_pages and load subsequent pages on demand rather than in a loop.

Do:

  • Fetch the first page and display it immediately
  • Load more pages as the user scrolls or explicitly requests them

Don't:

  • Loop through all pages at startup to "build a complete picture"
  • Set per=100 and iterate until has_more_pages is false

Use HTTP Caching

All responses include Cache-Control and ETag headers. Unauthenticated responses are max-age=300, public — your client can reuse them for 5 minutes without any network request. Authenticated responses are private, no-cache — your client may store them but must revalidate before each reuse.

To revalidate, send the ETag value from a previous response as If-None-Match:

GET /v3/channels/123
If-None-Match: "abc123"

If the resource hasn't changed, the API returns 304 Not Modified with no body, saving bandwidth. Single-resource endpoints (e.g., /v3/channels/:id, /v3/blocks/:id) also skip server-side work entirely on a match. Note that 304 responses still count against your rate limit.

Fetch Summaries Before Details

Start with lightweight list endpoints (e.g., a channel's first page of contents) before drilling into individual blocks or nested resources. Avoid eagerly resolving every connection or nested object — fetch details only when a user explicitly needs them.

Respect Rate Limits Gracefully

Monitor the X-RateLimit-Limit and X-RateLimit-Reset headers. If you receive a 429 response, wait until the reset window before retrying — don't retry in a tight loop. Consider adding exponential backoff and a short delay between sequential requests (e.g., 200–500ms) when making multiple calls.

Design for Partial Data

Channels can have tens of thousands of connections. Your application should function well with just the first page of results, not require the full dataset upfront. Display what you have and offer the user a way to load more.

Build Statically When Possible

If you're building a website that displays Are.na content, prefer static site generation (fetching data at build time) over live API requests on every page view. This eliminates rate limit concerns for your visitors and makes your site faster and more resilient. If you need fresher data, cache responses server-side with a reasonable TTL rather than proxying every request through to the API.

Avoid Write-Heavy Loops

If you're creating or connecting multiple blocks, batch your logic and add delays between write operations. Rapid-fire mutations can hit rate limits quickly and may trigger abuse detection.

    Log in
    Sign up