API documentation

The SQL Audit REST API lets you pull your SQL Server audits into CI/CD pipelines, monitoring scripts and automation tools.

Authentication

Every request needs a valid API key

Create an API key from your dashboard, then send it in the X-API-Key header on every request.

Authenticated request

curl -X GET "https://audit.databreizh.fr/api/v1/instances" \
  -H "X-API-Key: sqla_your_api_key"

Keep your keys secret

Never share an API key. Store keys in environment variables or a secrets manager, and revoke any key you suspect has leaked.

Rate limits

Each API key is allowed 100 requests per minute. Every response reports where you stand:

Header	Description
X-RateLimit-Limit	Requests allowed per window
X-RateLimit-Remaining	Requests left in the current window
X-RateLimit-Reset	When the counter resets (ISO 8601)

Response format

Every response uses the same JSON envelope:

Successful response

{
  "success": true,
  "data": {
    // Response payload
  },
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "total_pages": 3
  }
}

Error response

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Instance non trouvé",
    "details": null
  }
}

Branch on error.code, never on error.message: the code is stable, the message is human-readable French prose and may change without notice.

Language of catalog text

The payloads on this page show the default response

Catalog text (check_name, check_description, check_remediation, category_name) is served in the language of the request by /api/v1/checks and /api/v1/instances/{id}/findings. The language is resolved in this order: the NEXT_LOCALE cookie, the Referer header, the Accept-Language header, then French as the fallback — so a bare curl call gets French.

Asking for English labels

curl -X GET "https://audit.databreizh.fr/api/v1/checks?category=security" \
  -H "X-API-Key: sqla_your_api_key" \
  -H "Accept-Language: en"

Endpoints

GET
`/api/v1/instances`

List every SQL Server instance in your organization

Parameters

Name	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Results per page (default: 20, max: 100)
`environment`	string	Filter by environment (production, staging, development)
`min_score`	integer	Minimum global score
`max_score`	integer	Maximum global score

Example

curl -X GET "https://audit.databreizh.fr/api/v1/instances?environment=production" \
  -H "X-API-Key: sqla_your_api_key"

Response

{
  "success": true,
  "data": {
    "instances": [
      {
        "id": "uuid",
        "name": "PROD-SQL01",
        "hostname": "prod-sql01.local",
        "version": "SQL Server 2022",
        "edition": "Enterprise",
        "environment": "production",
        "score_global": 82,
        "score_security": 75,
        "score_configuration": 88,
        "score_files": 92,
        "score_backups": 90,
        "score_maintenance": 85,
        "score_agent": 78,
        "score_performance": 80,
        "score_reliability": 87,
        "score_updates": 70,
        "score_hardware": 95,
        "score_io": 82,
        "score_memory": 88,
        "score_queries": 72,
        "score_storedprocs": 90,
        "score_connections": 85,
        "score_dblevel": 78,
        "score_wait_statistics": 80,
        "score_query_store": 75,
        "score_linked_servers": 92,
        "score_blocking": 88,
        "score_db_settings": 82,
        "score_extended_events": 70,
        "score_encryption": 85,
        "score_capacity": 90,
        "score_database_mail": 78,
        "checks_total": 110,
        "checks_passed": 60,
        "checks_failed": 8,
        "checks_warning": 7,
        "last_audit_at": "2024-01-15T10:30:00Z",
        "created_at": "2024-01-01T00:00:00Z"
      }
    ]
  },
  "meta": { "total": 5, "page": 1, "per_page": 20 }
}

GET
`/api/v1/instances/{id}`

One instance in full, with its audit history

Parameters

Name	Type	Description
`id`*	uuid	Instance ID (in the path)

Example

curl -X GET "https://audit.databreizh.fr/api/v1/instances/instance-uuid" \
  -H "X-API-Key: sqla_your_api_key"

Response

{
  "success": true,
  "data": {
    "instance": {
      "id": "uuid",
      "name": "PROD-SQL01",
      "hostname": "prod-sql01.local",
      "version": "SQL Server 2022",
      "edition": "Enterprise",
      "score_global": 82,
      // ... every category score
    },
    "audits": [
      {
        "id": "audit-uuid",
        "score_global": 82,
        "collected_at": "2024-01-15T10:30:00Z",
        "checks_total": 110,
        "checks_passed": 60,
        "checks_failed": 8
      }
    ]
  }
}

GET
`/api/v1/instances/{id}/findings`

Findings from the most recent audit of an instance

Parameters

Name	Type	Description
`id`*	uuid	Instance ID (in the path)
`category`	string	Filter by category (security, backups, performance, and so on)
`status`	string	Filter by status (pass, fail, warning, info)
`severity`	string	Filter by severity (critical, high, medium, low, info)
`page`	integer	Page number
`per_page`	integer	Results per page

Example

curl -X GET "https://audit.databreizh.fr/api/v1/instances/uuid/findings?status=fail&severity=critical" \
  -H "X-API-Key: sqla_your_api_key"

Response

{
  "success": true,
  "data": {
    "findings": [
      {
        "id": "finding-uuid",
        "check_id": "SEC001",
        "category_id": "security",
        "status": "fail",
        "severity": "critical",
        "value": "1",
        "details": "Le compte SA est activé",
        "check_name": "Compte SA activé",
        "check_description": "Le compte SA doit être désactivé",
        "check_remediation": "ALTER LOGIN sa DISABLE",
        "category_name": "Sécurité",
        "category_color": "#ef4444"
      }
    ],
    "audit_id": "audit-uuid"
  },
  "meta": { "total": 8, "page": 1, "per_page": 20 }
}

POST
`/api/v1/upload`
Scope: write

Upload an audit CSV

Parameters

Name	Type	Description
`file`*	file	CSV file (multipart/form-data), or the CSV itself as a text/csv body

Example

# As multipart/form-data
curl -X POST "https://audit.databreizh.fr/api/v1/upload" \
  -H "X-API-Key: sqla_your_api_key" \
  -F "file=@audit_PROD-SQL01_2024-01-15.csv"

# As a raw CSV body
curl -X POST "https://audit.databreizh.fr/api/v1/upload" \
  -H "X-API-Key: sqla_your_api_key" \
  -H "Content-Type: text/csv" \
  --data-binary @audit.csv

Response

{
  "success": true,
  "data": {
    "instance_id": "uuid",
    "audit_id": "audit-uuid",
    "instance": {
      "name": "PROD-SQL01",
      "version": "SQL Server 2022",
      "hostname": "prod-sql01.local"
    },
    "stats": {
      "total": 75,
      "passed": 60,
      "failed": 8,
      "warnings": 7,
      "info": 0
    },
    "score": 82
  }
}

GET
`/api/v1/checks`

The full catalog of available checks

Parameters

Name	Type	Description
`category`	string	Filter by category
`severity`	string	Filter by severity
`enabled_only`	boolean	Enabled checks only (default: true)
`page`	integer	Page number
`per_page`	integer	Results per page

Example

curl -X GET "https://audit.databreizh.fr/api/v1/checks?category=security" \
  -H "X-API-Key: sqla_your_api_key"

Response

{
  "success": true,
  "data": {
    "checks": [
      {
        "id": "SEC001",
        "category_id": "security",
        "name": "Compte SA activé",
        "description": "Le compte SA doit être désactivé",
        "severity": "critical",
        "points_deduction": 20,
        "remediation": "ALTER LOGIN sa DISABLE",
        "doc_url": "https://learn.microsoft.com/...",
        "category_name": "Sécurité",
        "category_color": "#ef4444"
      }
    ],
    "categories": [
      {
        "id": "security",
        "name": "Sécurité",
        "description": "...",
        "icon": "shield",
        "color": "#ef4444",
        "weight": 15
      }
    ]
  },
  "meta": { "total": 75, "page": 1, "per_page": 20 }
}

Error codes

Code	HTTP	Description
UNAUTHORIZED	401	Missing or invalid API key
FORBIDDEN	403	The key lacks the scope this operation needs
NOT_FOUND	404	Resource not found
BAD_REQUEST	400	Malformed request
VALIDATION_ERROR	422	The payload failed validation
RATE_LIMITED	429	Rate limit exceeded
SERVER_ERROR	500	Internal server error

Full reference (OpenAPI 3.1)

This page covers the core endpoints. Idempotent imports (POST /api/v1/imports), signed webhooks (/api/v1/webhooks) and organization reporting (/api/v1/reports/*) are described in the OpenAPI document, which is the authority for this API.

Download the OpenAPI document (YAML)

Need help? Email us at contact@databreizh.fr

API documentation

Authentication

Rate limits

Response format

Language of catalog text

Endpoints

GET/api/v1/instances

Parameters

Example

Response

GET/api/v1/instances/{id}

Parameters

Example

Response

GET/api/v1/instances/{id}/findings

Parameters

Example

Response

POST/api/v1/uploadScope: write

Parameters

Example

Response

GET/api/v1/checks

Parameters

Example

Response

Error codes

Full reference (OpenAPI 3.1)

GET
`/api/v1/instances`

GET
`/api/v1/instances/{id}`

GET
`/api/v1/instances/{id}/findings`

POST
`/api/v1/upload`
Scope: write

GET
`/api/v1/checks`