API Documentation

Build integrations with the Invobi API to create and manage invoices programmatically.

Getting Started

The Invobi API allows you to programmatically create and manage invoices. To use the API, you'll need to create an API token from your account settings.

Authentication

All API requests must include your API token in the Authorization header:

Authorization: Bearer YOUR_API_TOKEN

Base URL

All API endpoints are relative to:

https://invobi.com/api/v1

Rate Limiting

API requests are limited to 100 requests per minute per token. If you exceed this limit, you'll receive a 429 Too Many Requests response.

All API responses include rate limit headers to help you track your usage:

HeaderDescription
X-RateLimit-LimitThe maximum number of requests allowed per minute (100)
X-RateLimit-RemainingThe number of requests remaining in the current window
X-RateLimit-ResetUnix timestamp when the rate limit window resets

Example response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1736544000

Invoices

GET/invoices

Returns a paginated list of all invoices for the authenticated user. Supports filtering by payment status.

Authentication: Bearer token with read permission

Parameters

NameTypeRequiredDescription
pageintegerNoPage number (default: 1)
per_pageintegerNoItems per page (default: 20, max: 100)
statusstringNoFilter by payment status: 'paid' or 'unpaid'

Response

{
  "invoices": [
    {
      "id": "abc123",
      "title": "Invoice #001",
      "issued_at": "2025-01-15",
      "due_at": "2025-02-15",
      "paid_at": "2025-01-20",
      "currency": "USD",
      ...
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Example

# List all invoices
curl -X GET "https://invobi.com/api/v1/invoices?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# List only paid invoices
curl -X GET "https://invobi.com/api/v1/invoices?status=paid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

# List only unpaid invoices
curl -X GET "https://invobi.com/api/v1/invoices?status=unpaid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/invoices/:id

Returns a single invoice by ID.

Authentication: Bearer token with read permission

Parameters

NameTypeRequiredDescription
idstringYesThe invoice ID

Response

{
  "invoice": {
    "id": "abc123",
    "title": "Invoice #001",
    "issued_at": "2025-01-15",
    "due_at": "2025-02-15",
    "currency": "USD",
    "locale": "US",
    "from_details": [...],
    "to_details": [...],
    "items": [...],
    "discounts": [...],
    "taxes": [...],
    "payment_details": [...]
  }
}

Example

curl -X GET "https://invobi.com/api/v1/invoices/abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
POST/invoices

Creates a new invoice using natural language. Describe your invoice in plain text, and AI will generate it for you.

Authentication: Bearer token with write permission

Parameters

NameTypeRequiredDescription
promptstringYesNatural language description of the invoice to create
llm_providerstringYesLLM provider to use (see supported providers below)
llm_api_keystringYesYour API key for the chosen LLM provider

Response

{
  "invoice": {
    "id": "new-invoice-id",
    "title": "Consulting Services - January 2025",
    "issued_at": "2025-01-15",
    "due_at": "2025-02-15",
    ...
  }
}

Example

curl -X POST "https://invobi.com/api/v1/invoices" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create an invoice for 10 hours of consulting at $150/hour for Acme Corp from John Smith at Smith LLC. Add 10% tax. Payment due in 30 days to Chase Bank account 1234567890.",
    "llm_provider": "gemini-25-flash",
    "llm_api_key": "YOUR_LLM_API_KEY"
  }'

Supported LLM Providers

You must provide your own API key for the chosen LLM provider:

ProviderValueGet API Key
Google Gemini 2.5 Flashgemini-25-flashGoogle AI Studio
Google Gemini 2.5 Flash Litegemini-25-flash-liteGoogle AI Studio
Google Gemini 2.5 Progemini-25-proGoogle AI Studio
Google Gemini 2.0 Flashgemini-20-flashGoogle AI Studio
Google Gemini 2.0 Flash Litegemini-20-flash-liteGoogle AI Studio
OpenAI GPT-4ogpt-4oOpenAI Platform
OpenAI GPT-4o Minigpt-4o-miniOpenAI Platform
OpenAI GPT-4 Turbogpt-4-turboOpenAI Platform
OpenAI GPT-4.1gpt-41OpenAI Platform
OpenAI GPT-4.1 Minigpt-41-miniOpenAI Platform

💡 Tip: gemini-25-flash offers the best balance of speed and quality for invoice generation.

GET/invoices/:id/download

Downloads the invoice as a PDF file.

Authentication: Bearer token with read permission

Parameters

NameTypeRequiredDescription
idstringYesThe invoice ID

Response

Returns the invoice as a PDF file with Content-Type: application/pdf

Example

curl -X GET "https://invobi.com/api/v1/invoices/abc123/download" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -o invoice.pdf
DELETE/invoices/:id

Deletes an invoice.

Authentication: Bearer token with write permission

Parameters

NameTypeRequiredDescription
idstringYesThe invoice ID

Response

{
  "deleted": true
}

Example

curl -X DELETE "https://invobi.com/api/v1/invoices/abc123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
POST/invoices/:id/mark-paid

Marks an invoice as paid with today's date.

Authentication: Bearer token with write permission

Parameters

NameTypeRequiredDescription
idstringYesThe invoice ID

Response

{
  "invoice": {
    "id": "abc123",
    "paid_at": "2025-01-15",
    ...
  }
}

Example

curl -X POST "https://invobi.com/api/v1/invoices/abc123/mark-paid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
POST/invoices/:id/mark-unpaid

Marks an invoice as unpaid by clearing the paid date.

Authentication: Bearer token with write permission

Parameters

NameTypeRequiredDescription
idstringYesThe invoice ID

Response

{
  "invoice": {
    "id": "abc123",
    "paid_at": null,
    ...
  }
}

Example

curl -X POST "https://invobi.com/api/v1/invoices/abc123/mark-unpaid" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Prompts

GET/prompts

Returns a list of all saved prompts for the authenticated user.

Authentication: Bearer token with read permission

Parameters

NameTypeRequiredDescription
labelstringNoFilter by label name (use __no_label__ for unlabeled prompts)
contentstringNoFilter by content (case-insensitive search)

Response

{
  "prompts": [
    {
      "id": "prompt-123",
      "user_id": "user-456",
      "prompt_text": "Invoice for consulting services...",
      "labels": [
        {"name": "Consulting", "color": "#3b82f6"}
      ],
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}

Example

curl -X GET "https://invobi.com/api/v1/prompts" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/prompts/:id

Returns a single prompt by ID.

Authentication: Bearer token with read permission

Parameters

NameTypeRequiredDescription
idstringYesThe prompt ID

Response

{
  "prompt": {
    "id": "prompt-123",
    "user_id": "user-456",
    "prompt_text": "Invoice for consulting services...",
    "labels": [
      {"name": "Consulting", "color": "#3b82f6"}
    ],
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Example

curl -X GET "https://invobi.com/api/v1/prompts/prompt-123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
POST/prompts

Creates a new saved prompt.

Authentication: Bearer token with write permission

Parameters

NameTypeRequiredDescription
prompt_textstringYesThe prompt text to save
labelsarrayNoArray of label objects with 'name' and 'color' properties

Response

{
  "prompt": {
    "id": "new-prompt-id",
    "user_id": "user-456",
    "prompt_text": "Invoice for consulting services...",
    "labels": [
      {"name": "Consulting", "color": "#3b82f6"}
    ],
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Example

curl -X POST "https://invobi.com/api/v1/prompts" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "Invoice for consulting services at $150/hour",
    "labels": [{"name": "Consulting", "color": "#3b82f6"}]
  }'
PUT/prompts/:id

Updates an existing prompt. At least one field must be provided.

Authentication: Bearer token with write permission

Parameters

NameTypeRequiredDescription
idstringYesThe prompt ID (in URL)
prompt_textstringNoThe updated prompt text
labelsarrayNoUpdated array of label objects with 'name' and 'color' properties

Response

{
  "prompt": {
    "id": "prompt-123",
    "user_id": "user-456",
    "prompt_text": "Updated invoice prompt...",
    "labels": [
      {"name": "Updated", "color": "#10b981"}
    ],
    "created_at": "2025-01-15T10:30:00Z"
  }
}

Example

curl -X PUT "https://invobi.com/api/v1/prompts/prompt-123" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt_text": "Updated invoice prompt text",
    "labels": [{"name": "Updated", "color": "#10b981"}]
  }'
DELETE/prompts/:id

Deletes a prompt.

Authentication: Bearer token with write permission

Parameters

NameTypeRequiredDescription
idstringYesThe prompt ID

Response

{
  "deleted": true
}

Example

curl -X DELETE "https://invobi.com/api/v1/prompts/prompt-123" \
  -H "Authorization: Bearer YOUR_API_TOKEN"
GET/prompts/labels

Returns a list of all unique label names used by the authenticated user's prompts.

Authentication: Bearer token with read permission

Response

{
  "labels": ["Consulting", "Development", "Design"]
}

Example

curl -X GET "https://invobi.com/api/v1/prompts/labels" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Error Handling

The API uses standard HTTP status codes to indicate success or failure:

StatusDescription
200 OKRequest succeeded
201 CreatedResource created successfully
400 Bad RequestInvalid request body or parameters
401 UnauthorizedMissing or invalid API token
403 ForbiddenInsufficient permissions
404 Not FoundResource not found
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error

Error responses include a JSON body with an error message:

{
  "error": "Invalid or expired API token"
}