Documentation
Get Started

API

Learn how to interact with the oJo API.

Base URL

https://api.ojo.so

Authentication

To authenticate with the API, you need to provide an API key in the Authorization header.

Authorization: Bearer <Your API Key>

You can obtain your API key from the API settings (opens in a new tab).

Response Codes

The API uses standard HTTP response codes to indicate the success or failure of an API request.

  • 200 OK - Everything worked as expected.
  • 400 Bad Request - The request was unacceptable, often due to missing a required parameter.
  • 401 Unauthorized - No valid API key provided.
  • 402 Payment Required - The request requires payment.
  • 403 Forbidden - The API key doesn't have permissions to perform the request.
  • 404 Not Found - The requested resource doesn't exist.
  • 408 Request Timeout - The request took too long to process.
  • 422 Unprocessable Entity - The request was well-formed but was unable to be followed due to validation errors.
  • 429 Too Many Requests - Too many requests hit the API too quickly.
  • 500 Internal Server Error - We had a problem with our server. Try again later.
  • 503 Service Unavailable - We're temporarily offline for maintenance. Please try again later.

Rate Limits

The oJo API implements endpoint-specific rate limiting to ensure fair usage and system stability. Rate limits are tracked per user and enforced across all API requests.

Current Rate Limits

Endpoint TypeRate LimitTime WindowBlock Duration
Image Operations60 request60 seconds120 seconds
Template Operations30 requests60 seconds120 seconds

When you make an API request, the response will include headers that provide information about your current rate limit status:

X-RateLimit-Policy: <endpoint-type>:<requests>/<seconds>s
X-RateLimit-Limit: <maximum requests allowed>
X-RateLimit-Remaining: <requests remaining>
X-RateLimit-Reset: <ISO timestamp when the limit resets>

Rate Limit Exceeded

If you exceed the rate limit, you'll receive a 429 Too Many Requests response with the following headers:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Policy: <endpoint-type>:<requests>/<seconds>s
X-RateLimit-Limit: <maximum requests allowed>
X-RateLimit-Remaining: 0
X-RateLimit-Reset: <ISO timestamp when the limit resets>
Retry-After: <seconds until next request is allowed>

Best Practices

To work effectively with these rate limits:

  1. Monitor the X-RateLimit-Remaining header to track your remaining requests
  2. Use the X-RateLimit-Reset timestamp to schedule requests appropriately
  3. When receiving a 429 response, wait for the duration specified in the Retry-After header before retrying
  4. Implement exponential backoff in your retry logic
  5. Consider implementing request queuing for high-volume operations

Example Response Headers

For image operations:

X-RateLimit-Policy: image:60/60s
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2024-11-06T15:30:45.066Z
Retry-After: 87

For template operations:

X-RateLimit-Policy: template:30/60s
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 29
X-RateLimit-Reset: 2024-11-06T15:30:45.066Z

Resource Limits

To ensure optimal performance and fair usage, the API imposes limits on the size and type of a resource that can be processed:

  • Document: 1MB
  • Script: 1MB
  • Stylesheet: 1MB
  • Image: 5MB
  • Font: 1MB

The total size of all resources for a single request must not exceed 10MB.

Resources must be served over HTTPS, except for images which can also use data URIs.

If a resource exceeds its individual limit or contributes to exceeding the total limit, it will be blocked, and you may receive an error message.

Caveats

oJo API is currently in public beta and subject to change. We will do our best to notify you of any changes.

IntroductionCreate Image from Template