API Documentation

Everything you need to integrate with the Girard AI API

OpenAPI Spec

Download JSON

API Keys

Manage keys

Webhooks

Event notifications

Authentication

All API requests require an API key. Include your key in the X-API-Key header.

curl https://www.girardai.com/api/v1/workflows \
  -H "X-API-Key: your_api_key_here"

Generate API keys in the API Keys section of your dashboard.

Base URL

https://www.girardai.com/api/v1

API Versioning

The Girard AI API uses URL path versioning. The current version is v1.

Versioning Strategy

URL Path Versioning: Version is included in the URL path (e.g., /api/v1/). This makes the version explicit and easy to manage.
Semantic Versioning: Major versions (v1, v2) indicate breaking changes. Minor updates are backward-compatible within the same major version.
Stable by Default: All endpoints in a released version are stable unless marked as beta.

Backward Compatibility Guarantees

Within a major version, we guarantee the following will remain stable:

  • Existing endpoint URLs and HTTP methods
  • Required request parameters and their types
  • Response structure for successful requests
  • Error response format and error codes
  • Authentication mechanism

Additive changes (new optional fields, new endpoints) may be added without version bump.

Deprecation Policy

  • 12-month notice: Deprecated versions are supported for at least 12 months after deprecation announcement.
  • Migration guides: We provide detailed migration guides when releasing new major versions.
  • Deprecation headers: Deprecated endpoints return a X-API-Deprecated header with the sunset date.
  • Email notifications: API key owners receive email notifications about upcoming deprecations.

API Versions

VersionStatusReleasedEnd of Life
v1CurrentJanuary 2026—

Rate Limiting

API requests are rate limited based on your plan. Rate limit information is included in response headers:

  • X-RateLimit-LimitMaximum requests per window
  • X-RateLimit-RemainingRequests remaining in current window
  • X-RateLimit-ResetUnix timestamp when the window resets

Official SDKs

Use our official SDKs to integrate with the Girard AI API in your preferred language.

Py

Python

pip install girardai

from girardai import Girard AI

client = Girard AI(api_key="your_key")
result = client.workflows.execute(
    "wf_abc123",
    input="Generate content"
)
print(result.output)
Python 3.9+Type Hints
TS

Node.js / TypeScript

npm install girardai

import { Girard AI } from 'girardai';

const client = new Girard AI({
  apiKey: 'your_key'
});
const result = await client.workflows
  .execute('wf_abc123', {
    input: 'Generate content'
  });
console.log(result.output);
Node.js 18+TypeScript

SDK Features

  • Full TypeScript / Python type hints
  • Automatic pagination handling
  • Built-in error handling
  • Execution polling with timeout

Endpoints

Workflows

GET/workflowsList all workflows
POST/workflowsCreate a new workflow
GET/workflows/{id}Get workflow details
PATCH/workflows/{id}Update a workflow
DELETE/workflows/{id}Delete a workflow

Runs

POST/workflows/{id}/executeExecute a workflow
GET/workflows/{id}/runsList workflow runs
GET/runs/{id}Get run details

Example: Execute a Workflow

curl -X POST https://www.girardai.com/api/v1/workflows/{workflow_id}/execute \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "input": "Write a product description for a wireless mouse",
    "variables": {
      "tone": "professional",
      "maxWords": 100
    }
  }'

Response:

{
  "success": true,
  "data": {
    "runId": "run_abc123",
    "status": "COMPLETED",
    "output": "Introducing our ergonomic wireless mouse...",
    "tokensUsed": 150,
    "durationMs": 2340
  }
}

Error Handling

All errors return a consistent JSON structure:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid workflow steps",
    "details": { ... },
    "hint": "Please fix the step validation errors and try again."
  }
}

Error Codes

INVALID_API_KEY→401
RATE_LIMITED→429
VALIDATION_ERROR→400
RESOURCE_NOT_FOUND→404
WORKFLOW_INACTIVE→400
AI_PROVIDER_ERROR→500
INTERNAL_ERROR→500

Need Help?

Have questions about the API? Check out our developer guides or contact support.