Getting Started with Qovery API

Introduction

Welcome to the Qovery API Reference! The Qovery API is a REST API that allows you to programmatically manage your entire infrastructure.

Authentication

All API requests require authentication using an API token. Include your API token in the Authorization header of every request:

Authorization: Token YOUR_API_TOKEN

Token vs Bearer: Qovery API supports two authentication schemes:

Token (Recommended): Use for API tokens generated from Qovery Console. Format: Authorization: Token <your-api-token>
Bearer: Use for JWT tokens only (e.g., from OAuth flows). Format: Authorization: Bearer <jwt-token>

For third-party API integrations and programmatic access, always use Token authentication with API tokens. JWT tokens with Bearer are intended for internal use cases only and are not recommended for external API calls.

Creating an API Token

Log in to the Qovery Console
Navigate to Organization Settings → API Tokens
Click Generate Token
Give your token a descriptive name and set appropriate permissions
Copy and save the token securely (it will only be displayed once)

Example Request

curl -X GET "https://api.qovery.com/organization" \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json"

Replace YOUR_API_TOKEN with your actual API token generated from Qovery Console.

Token Security

API tokens provide access to your infrastructure. Keep them secure:

Never commit tokens to version control
Store them in environment variables or secrets management systems
Rotate tokens regularly
Use minimal required permissions

Official SDKs

Qovery provides official client libraries to simplify API integration:

TypeScript/JavaScript

Install via npm:

npm install @qovery/client

Usage:

import { QoveryClient } from '@qovery/client';

const client = new QoveryClient({
  apiToken: process.env.QOVERY_API_TOKEN
});

// Get organization
const org = await client.organization.get();
console.log(`Organization: ${org.name}`);

// List projects
const projects = await client.projects.list();
projects.forEach(project => {
  console.log(`Project: ${project.name}`);
});

Resources:

Go

Install via go get:

go get github.com/qovery/qovery-client-go

Usage:

package main

import (
    "context"
    "fmt"
    "os"

    "github.com/qovery/qovery-client-go"
)

func main() {
    token := os.Getenv("QOVERY_API_TOKEN")

    client := qovery.NewAPIClient(&qovery.Configuration{
        DefaultHeader: map[string]string{
            "Authorization": fmt.Sprintf("Token %s", token),
        },
    })

    ctx := context.Background()

    // Get organization
    org, _, err := client.OrganizationApi.GetOrganization(ctx)
    if err != nil {
        panic(err)
    }

    fmt.Printf("Organization: %s\n", org.Name)

    // List projects
    projects, _, err := client.ProjectsApi.ListProjects(ctx, org.Id)
    if err != nil {
        panic(err)
    }

    for _, project := range projects.Results {
        fmt.Printf("Project: %s\n", project.Name)
    }
}

Resources:

Other Languages

For other languages, you can:

Use the REST API directly - All endpoints are documented in this reference
Generate a client - Use the OpenAPI specification with code generation tools like:
- OpenAPI Generator
- Swagger Codegen

Base URL

All API requests should be made to:

https://api.qovery.com

API Versioning

The current API version is included in the URL path:

https://api.qovery.com

We maintain backward compatibility within a major version. Breaking changes will result in a new major version (v2, v3, etc.).

Rate Limits

1000 requests per hour per API token
Rate limit headers are included in all responses:
- X-RateLimit-Limit: Maximum requests per window
- X-RateLimit-Remaining: Remaining requests
- X-RateLimit-Reset: Time when limit resets (Unix timestamp)

If you exceed the rate limit, you’ll receive a 429 Too Many Requests response.

Response Format

All successful responses return JSON:

{
  "id": "resource-id",
  "name": "resource-name",
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

Error Handling

Error responses include a status code and error details:

{
  "status": 400,
  "error": "Bad Request",
  "message": "Validation error: name is required"
}

Common Status Codes

Code	Description
`200`	Success
`201`	Created
`204`	No Content
`400`	Bad Request - Invalid input
`401`	Unauthorized - Invalid or missing token
`403`	Forbidden - Insufficient permissions
`404`	Not Found - Resource doesn’t exist
`429`	Too Many Requests - Rate limit exceeded
`500`	Internal Server Error

Pagination

List endpoints support pagination:

GET /projects?page=1&page_size=20

Response includes pagination metadata:

{
  "results": [...],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total_count": 150,
    "total_pages": 8
  }
}

Try It Out

Use the interactive API reference on the right to explore endpoints and make test requests. Each endpoint includes:

Request parameters - Path, query, and body parameters
Example requests - Code samples in multiple languages
Responses - Expected response formats
Try it out - Test the API directly from the documentation

Next Steps

Explore Endpoints

Browse all available API endpoints in the reference

Code Examples

See practical examples and common workflows

TypeScript SDK

Use the official TypeScript client

Go SDK

Use the official Go client

Support

Need help with the API?

GitHub Issues: Report bugs or request features
Email Support: support@qovery.com

​Introduction

​Authentication

​Creating an API Token

​Example Request

​Token Security

​Official SDKs

​TypeScript/JavaScript

​Go

​Other Languages

​Base URL

​API Versioning

​Rate Limits

​Response Format

​Error Handling

​Common Status Codes

​Pagination

​Try It Out

​Next Steps

Explore Endpoints

Code Examples

TypeScript SDK

Go SDK

​Support

Introduction

Authentication

Creating an API Token

Example Request

Token Security

Official SDKs

TypeScript/JavaScript

Go

Other Languages

Base URL

API Versioning

Rate Limits

Response Format

Error Handling

Common Status Codes

Pagination

Try It Out

Next Steps

Support