API Usage Patterns

Best practices for building reliable, efficient integrations with the J77.ai API.

Batch Builds Overnight

The most common pattern for high-volume content production: queue builds in the evening and collect results in the morning. A simple script can create 20+ builds, poll for completion, and download all deliverables by the time your team starts work.

1. Check your token balance with GET /api/v1/tokens/balance before starting.
2. Create builds with POST /api/v1/builds, one per article. Use Idempotency-Key headers so retries are safe.
3. Poll GET /api/v1/builds/:id at intervals (e.g. every 30 seconds) until status is completed.
4. Download each deliverable with GET /api/v1/deliverables/:id/download?format=md.

Tip: stagger your build creation by a few seconds to avoid hitting the 10 req/min build rate limit.

Idempotency Keys

Always send an Idempotency-Key header with POST /api/v1/builds. This ensures that if a request is retried (network timeout, server error, etc.), you don't create a duplicate build or waste tokens.

Good patterns for idempotency keys:

• batch-2026-02-22-post-1 — date + sequence for batch jobs
• client-acme-weekly-blog-2026-w08 — client + cadence for agency workflows
• A UUID generated once per logical operation

If the same key is reused within the idempotency window (24 hours), the API returns the existing build with idempotent: true instead of creating a new one.

Token Balance Management

Always check your balance before creating builds. The API returns 402 INSUFFICIENT_TOKENS withrequired, available, and shortfall fields when you don't have enough tokens.

Build cost depends on several factors: number of pages, research mode, max mode, image generation, and content kind. For single standard blog posts with research, expect 1 token. Suites cost more depending on page count. Use the token calculator to estimate costs.

Rate Limit Handling

The API enforces rate limits per API key:

• 60 req/min — most endpoints
• 10 req/min — POST /builds
• 20 req/min — suggest and image endpoints

When rate-limited, the API returns 429 with rate-limit headers: X-RateLimit-Limit,X-RateLimit-Remaining, and X-RateLimit-Reset. Implement exponential backoff:

1. On 429, read the X-RateLimit-Reset header (Unix timestamp).
2. Wait until that time, or use exponential backoff (1s, 2s, 4s, 8s...).
3. Retry the request.

Scope Management

Create API keys with the minimum scopes needed for each use case:

• read only — for dashboards and monitoring tools that just fetch data
• read + write — for tools that manage targets and library content but don't create builds
• read + write + builds — for full automation pipelines that create content

You can create multiple keys with different scopes for different parts of your system. Rotate keys periodically and revoke any that are no longer needed.

Error Handling

All API errors follow a consistent shape:

{ "error": "Human-readable message", "code": "ERROR_CODE", "details": {} }

Handle these error codes in your integration:

• UNAUTHORIZED / INVALID_API_KEY — check your key format and that it hasn't been revoked
• SCOPE_REQUIRED — your key is missing a required scope for this endpoint
• RATE_LIMITED — back off and retry
• INSUFFICIENT_TOKENS — purchase more tokens before retrying
• VALIDATION_ERROR — check request body against the API docs

Next Steps