Generate Wrapper

POST /resources/wrappers/generate

Generate a new AI-powered wrapper for sustainability indicators. The wrapper will be created asynchronously - the endpoint returns immediately with wrapper details, while code generation and execution happen in the background via a message queue.

Authentication

This endpoint requires authentication. Include your API key in the request headers.

Request Body

source_type

string

required

Type of data source. Must be one of:

API - REST API endpoint
CSV - CSV file
XLSX - Excel file

source_config

object

required

Source-specific configuration. The structure varies based on source_type.

Show CSV Source Config

file_id

string

required

File ID of the uploaded CSV file

location

string

Computed file path (automatically populated by backend)

Show XLSX Source Config

file_id

string

required

File ID of the uploaded XLSX file

location

string

Computed file path (automatically populated by backend)

Show API Source Config

location

string

required

API endpoint URL

auth_type

string

default:"none"

Authentication type: bearer, api_key, basic, or none

api_key

string

API key for authentication (when auth_type is api_key)

api_key_header

string

default:"X-API-Key"

Header name for API key

bearer_token

string

Bearer token for authentication (when auth_type is bearer)

username

string

Username for basic authentication

password

string

Password for basic authentication

timeout_seconds

integer

default:"30"

Request timeout in seconds

date_field

string

Field name for date/timestamp in API response

value_field

string

Field name for the indicator value in API response

custom_headers

object

Additional custom headers as key-value pairs

query_params

object

Default query parameters as key-value pairs

metadata

object

required

Indicator metadata describing the sustainability metric.

Show Metadata Properties

name

string

required

Name of the sustainability indicator

domain

string

required

Domain (e.g., Environment, Social)

subdomain

string

required

Subdomain classification

description

string

required

Detailed description of the indicator

unit

string

required

Unit of measurement

source

string

required

Data source name

scale

string

required

Scale (e.g., National, Regional)

governance_indicator

boolean

required

Whether this is a governance indicator

carrying_capacity

number

Maximum capacity value (optional)

periodicity

string

required

Data collection frequency

auto_create_resource

boolean

default:"true"

Automatically create a resource for this wrapper

Response

wrapper_id

string

Unique identifier for the generated wrapper

resource_id

string

Associated resource ID (if auto_create_resource is true)

metadata

object

The indicator metadata from the request

source_type

string

Type of data source (API, CSV, or XLSX)

source_config

object

Source-specific configuration

generated_code

string

Generated wrapper code (null during generation)

created_at

string

ISO 8601 timestamp of creation

updated_at

string

ISO 8601 timestamp of last update

completed_at

string

ISO 8601 timestamp of completion (null if not completed)

status

string

Current status: pending, generating, creating_resource, executing, stopped, completed, or error

error_message

string

Error message if status is error

execution_log

array

Array of execution log messages

last_health_check

string

ISO 8601 timestamp of last health check

last_data_sent

string

ISO 8601 timestamp of last data transmission

data_points_count

integer

Number of data points processed

monitoring_details

object

Type-specific monitoring information

phase

string

Current execution phase: historical or continuous

high_water_mark

string

Newest data point timestamp ever sent (for resumable execution)

low_water_mark

string

Oldest data point timestamp ever sent (for resumable execution)

execution_result

object

Result of the last execution (if available)

Example Request

cURL

curl -X POST https://api.example.com/resources/wrappers/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "source_type": "API",
    "source_config": {
      "location": "https://data-api.example.com/climate/temperature",
      "auth_type": "bearer",
      "bearer_token": "your-api-token",
      "timeout_seconds": 30,
      "date_field": "timestamp",
      "value_field": "temperature_celsius"
    },
    "metadata": {
      "name": "Average Temperature",
      "domain": "Environment",
      "subdomain": "Climate",
      "description": "Average daily temperature in degrees Celsius",
      "unit": "°C",
      "source": "National Climate Service",
      "scale": "National",
      "governance_indicator": false,
      "periodicity": "Daily"
    },
    "auto_create_resource": true
  }'

Example Response

{
  "wrapper_id": "550e8400-e29b-41d4-a716-446655440000",
  "resource_id": "res_123456789",
  "metadata": {
    "name": "Average Temperature",
    "domain": "Environment",
    "subdomain": "Climate",
    "description": "Average daily temperature in degrees Celsius",
    "unit": "°C",
    "source": "National Climate Service",
    "scale": "National",
    "governance_indicator": false,
    "carrying_capacity": null,
    "periodicity": "Daily"
  },
  "source_type": "API",
  "source_config": {
    "location": "https://data-api.example.com/climate/temperature",
    "auth_type": "bearer",
    "bearer_token": "your-api-token",
    "timeout_seconds": 30,
    "date_field": "timestamp",
    "value_field": "temperature_celsius",
    "custom_headers": {},
    "query_params": {}
  },
  "generated_code": null,
  "created_at": "2026-03-03T10:30:00Z",
  "updated_at": "2026-03-03T10:30:00Z",
  "completed_at": null,
  "status": "pending",
  "error_message": null,
  "execution_log": [],
  "last_health_check": "2026-03-03T10:30:00Z",
  "last_data_sent": null,
  "data_points_count": 0,
  "monitoring_details": {},
  "phase": "historical",
  "high_water_mark": null,
  "low_water_mark": null,
  "execution_result": null
}

Error Responses

400 Bad Request

Invalid wrapper generation request. Common causes:

Missing required fields
Invalid source_type value
File not found for CSV/XLSX sources
Invalid configuration parameters

{
  "detail": "Invalid request: File not found: file_abc123"
}

503 Service Unavailable

External service error during wrapper generation:

Connection error to external services
Timeout communicating with dependencies
Database unavailable

{
  "detail": "Service unavailable: Connection timeout"
}

Resources

Wrappers

File Management

Health

POST /resources/wrappers/generate

Authentication

Request Body

Response

Example Request

Example Response

Error Responses

Build docs developers (and LLMs) love

Resources

Wrappers

File Management

Health

​POST /resources/wrappers/generate

​Authentication

​Request Body

​Response

​Example Request

​Example Response

​Error Responses

Build docs developers (and LLMs) love

POST /resources/wrappers/generate

Authentication

Request Body

Response

Example Request

Example Response

Error Responses