Skip to content
CloudOptifyDocs

API overview

The public REST API exposes CloudOptify’s core capabilities to your own systems: read cost data, manage groups, alerts, and reports, and trigger scans.

Base URL

Section titled “Base URL”
https://app.cloudoptify.com/api/v1

All endpoints are versioned under /api/v1. Requests and responses are JSON.

Authentication

Section titled “Authentication”

Three methods, all resolving to a Bearer token in the Authorization header:

Method Best for Docs
API tokens Scripts and direct integrations API tokens
OAuth 2.0 client credentials Machine-to-machine services OAuth 2.0
OAuth 2.0 authorization code + PKCE Apps acting on behalf of a user OAuth 2.0
Terminal window
curl -H "Authorization: Bearer <token>" \
  https://app.cloudoptify.com/api/v1/cost/summary

Scopes

Section titled “Scopes”

Access is governed by three scopes, intersected with the caller’s role:

Scope Grants
read GET endpoints — cost, findings, groups, alerts, reports, scan status.
write Create/update/delete — groups, alerts, reports, acknowledgements.
run Triggering scans.

A request without the required scope returns 403 with an insufficient_scope error.

Conventions

Section titled “Conventions”
  • Errors use a consistent envelope: { "error": "<code>", "message": "<human readable>" }, with standard ProblemDetails for validation failures.
  • List endpoints support pagination parameters.
  • Rate limiting & quota are plan-based: a per-minute limit per caller (429 with Retry-After, error: "rate_limit_exceeded") and a monthly quota per organization that resets on the 1st (429, error: "quota_exceeded"). Responses carry X-RateLimit-Limit/Remaining and X-Quota-Limit/Remaining headers so clients can self-pace. Higher tiers get higher limits; Enterprise is effectively unlimited (fair use).

Full endpoint reference

Section titled “Full endpoint reference”

The complete, always-current endpoint reference (generated from the live OpenAPI specification) is available in the portal under API Access → API reference, including request/response schemas you can try directly.