> ## Documentation Index > Fetch the complete documentation index at: https://docs.aurous-labs.com/llms.txt > Use this file to discover all available pages before exploring further. # Register a webhook endpoint > Mints a new endpoint, generates a signing secret, and returns the secret EXACTLY ONCE in the `secret` field. Store it on your side — subsequent reads return `secret: null`. Subscribe to `["*"]` to receive every event in the v1.0 taxonomy (the wildcard is expanded at create time; new event types added later do NOT auto-subscribe). ## OpenAPI ````yaml /api-reference/openapi.json post /v1/webhook_endpoints openapi: 3.0.0 info: title: Aurous Labs API description: >- Generate AI images with custom LoRA styles. ## Authentication All requests require an API key passed in the `X-Api-Key` header. Create API keys in your [dashboard](https://app.aurous-labs.com/dashboard/api-keys). ## Closed-beta access gate API keys are scoped to a user. If that user's account is not approved for the closed beta, every request returns `403` with one of these `error.code` values: - `account_pending` — awaiting review - `account_rejected` — declined post-signup - `account_suspended` — was approved, then suspended There is no retry — contact support to be approved. The same codes are emitted by the WebSocket gateway via 4001 close. ## Common headers Every response carries `Aurous-Request-Id` (a server-minted `req_` for support tracing) and `Aurous-Version` (the API version applied to the response). Optionally pin a version on the request with `Aurous-Version: YYYY-MM-DD` — defaults to your team's pinned version. ## Quick Start ```bash curl -X POST https://api.aurous-labs.com/v1/images \ -H "X-Api-Key: al_live_your_key" \ -H "Content-Type: application/json" \ -d '{"prompt": "A golden sunset over mountains", "lora_id": "your-lora-id", "size": "2k_1_1"}' ``` version: 1.0.0 contact: {} servers: - url: https://api.aurous-labs.com description: Production - url: https://api.preprod.aurous-labs.com description: Preprod (staging) security: [] tags: - name: Seedance (raw) description: >- Drop-in raw passthrough for Seedance video generation. Point the official Seedance provider SDK at this API's base URL and authenticate with your Aurous API key in the `X-Api-Key` header — request bodies are forwarded to the provider verbatim and responses come back shape-identical, so you keep the provider's exact request/response shapes. Task ids are Aurous-native `vid_…` ids. Billing rides response headers, not the body: `Aurous-Credits-Held` on the create response and `Aurous-Credits-Charged` on a settled, succeeded task read — the body itself stays provider-shaped. paths: /v1/webhook_endpoints: post: tags: - Public API (v1) summary: Register a webhook endpoint description: >- Mints a new endpoint, generates a signing secret, and returns the secret EXACTLY ONCE in the `secret` field. Store it on your side — subsequent reads return `secret: null`. Subscribe to `["*"]` to receive every event in the v1.0 taxonomy (the wildcard is expanded at create time; new event types added later do NOT auto-subscribe). operationId: V1WebhooksController_create parameters: - name: Aurous-Version in: header required: false description: >- Optional API version pin (YYYY-MM-DD). Defaults to your team's pinned version, or the system default `2026-07-16` for unauthenticated requests. schema: type: string example: '2026-07-16' pattern: ^\d{4}-\d{2}-\d{2}$ requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateWebhookEndpointDto' responses: '201': description: Endpoint created content: application/json: schema: $ref: '#/components/schemas/WebhookEndpointResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '400': description: >- Validation failed — a malformed body, or an `api_key_id` that does not resolve to an API key owned by your team (error code `api_key_not_found`, param `api_key_id`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '403': description: >- Account not approved for closed beta. error.code is one of `account_pending`, `account_rejected`, `account_suspended`. There is no retry — contact support to be approved. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Aurous-Request-Id: description: Server-minted request id. Quote this in support tickets. schema: type: string example: req_01HXMQ7Z3K8Y2NABCDEFGHJKMP Aurous-Version: description: API version pin applied to this response (YYYY-MM-DD). schema: type: string example: '2026-07-16' X-RateLimit-Limit: description: Bucket capacity (max tokens) for this endpoint class. schema: type: integer example: 120 X-RateLimit-Remaining: description: Tokens remaining after this request. schema: type: integer example: 119 X-RateLimit-Reset: description: >- Epoch seconds when the bucket would be full again, assuming no further requests. schema: type: integer example: 1700000060 Retry-After: description: >- Seconds to wait before retrying. Present on 429 (rate limit) and on 503 provider_unavailable. Prefer this over computing X-RateLimit-Reset − now. schema: type: integer example: 12 security: - api-key: [] components: schemas: CreateWebhookEndpointDto: type: object properties: url: type: string description: HTTPS endpoint to deliver events to. Plain `http://` is rejected. example: https://api.acme.dev/aurous-webhook maxLength: 2048 events: description: >- Subscribed event types. Pass `["*"]` to subscribe to every event currently in the v1.0 taxonomy (the wildcard is expanded at create time — future event additions do NOT auto-subscribe). Available events include `image.*`, `video.*`, `character.completed` / `character.failed` / `character.cancelled`, `usage.balance_low`, and `webhook.endpoint_disabled`. example: - character.completed - character.failed - image.completed type: array items: type: string description: type: string description: Optional human-readable label shown in the dashboard. example: Production webhook metadata: type: object description: >- Optional structured metadata. Echoed verbatim on subsequent reads. Max 50 keys, string values <=500 chars. example: env: prod team: integrations api_key_id: type: string description: >- Bind this endpoint to a single API key by its public `key_…` id. When set, the endpoint receives ONLY events generated with that key (most-specific routing); unscoped endpoints stop receiving that key's events. Omit (or pass null) for a catch-all endpoint. The key must belong to your team. On PATCH: null = unbind, omit = leave unchanged. example: key_06FD019S0HGR87NSH2KA72HZAC nullable: true required: - url - events WebhookEndpointResponse: type: object properties: id: type: string example: we_01HXMQ7Z3K8Y2NABCDEFGHJKMN description: Opaque endpoint id (we_). object: type: string example: webhook_endpoint url: type: string example: https://api.acme.dev/aurous-webhook events: example: - image.completed type: array items: type: string description: type: object example: Production webhook nullable: true secret_preview: type: string example: whsec_8jK...ABCD description: >- Truncated preview of the active secret. Always present in dashboard hints. secret: type: object example: whsec_8jKpQ4nXabc1234abc... description: >- Plaintext webhook secret. Returned EXACTLY ONCE on POST + /rotate_secret responses; null on every other read. Store on your side and use to verify the `Aurous-Webhook-Signature` header. nullable: true is_active: type: boolean example: true consecutive_failures: type: number example: 0 description: >- Consecutive 4xx/5xx/timeout/connect errors since the last successful delivery. The endpoint auto-disables at >=20 with no success in 24h (emits `webhook.endpoint_disabled` to other active endpoints + an email to the team owner). last_success_at: type: object example: '2026-05-04T01:00:00Z' nullable: true description: Timestamp of the most recent 2xx delivery; null if never. last_failure_at: type: object example: '2026-05-04T00:55:00Z' nullable: true description: >- Timestamp of the most recent failed delivery (4xx/5xx/timeout/connect/TLS); null if never. metadata: type: object example: {} description: Echoed customer metadata. api_key_id: type: string example: key_06FD019S0HGR87NSH2KA72HZAC nullable: true description: >- Public id of the API key this endpoint is bound to, or null for a catch-all endpoint. When set, only events generated with that key are delivered here (most-specific routing). Reverts to null if the key is deleted. api_key_name: type: string example: Production key nullable: true description: Display name of the bound API key; null when unscoped (catch-all). created_at: type: string example: '2026-05-03T14:00:00Z' updated_at: type: string example: '2026-05-03T14:00:00Z' required: - id - object - url - events - secret_preview - is_active - consecutive_failures - last_success_at - last_failure_at - metadata - created_at - updated_at ErrorResponse: type: object properties: error: description: Error payload allOf: - $ref: '#/components/schemas/ErrorPayload' required: - error ErrorPayload: type: object properties: type: type: string description: Broad error category example: invalid_request enum: - invalid_request - authentication - not_found - rate_limit - server_error code: type: string description: >- Stable error code (programmatic discriminator). Closed-beta gate emits one of `account_pending`, `account_rejected`, `account_suspended` on 403. example: balance_too_low enum: - invalid_request - missing_field - invalid_format - value_out_of_range - unsupported_lora_for_mode - generation_not_cancellable - prompt_blocked - reference_blocked - output_moderation_rejected - unknown_version - mutually_exclusive_input - character_not_ready - parameter_invalid_combination - style_retired - parameter_invalid - too_many_reference_images - action_not_available - upload_invalid - balance_too_low - idempotency_key_in_use - api_key_not_found - payload_too_large - missing_api_key - invalid_api_key - revoked_api_key - resource_not_found - forbidden_resource - account_pending - account_rejected - account_suspended - already_approved - already_rejected - already_suspended - invalid_reinstate_target - invalid_suspend_target - cannot_moderate_admin - too_many_requests - concurrency_limit_exceeded - tpm_rate_limit_exceeded - internal_error - provider_unavailable - provider_timeout - provider_not_configured - invalid_time_range - invalid_bucket_width - too_many_buckets - too_many_group_by - invalid_filter - invalid_page_token - export_too_large - user_already_exists - self_invite_forbidden - invite_link_failed - invite_rate_limited - model_not_found - model_disabled - model_wrong_kind - max_tokens_exceeds_hard_cap - chat_model_misconfigured - embeddings_input_too_large - embeddings_unsupported_dimensions - pricing_frozen - provider_rate_limited - chat_provider_request_invalid - chat_provider_auth_failed - chat_provider_unavailable - max_input_tokens_exceeded - chat_provider_unknown_error - embeddings_provider_unknown_error - embeddings_batch_not_supported - embeddings_input_too_many_items - embeddings_video_unsupported - encoding_format_unsupported - missing_max_tokens_no_model_default - chat_cancel_target_not_found - chat_completion_not_found - chat_cancel_target_already_terminal - chat_cancel_target_not_cancellable - tool_choice_required_unsupported - response_format_too_large - response_format_too_deep - invalid_cursor - invalid_cursor_for_endpoint - model_slug_exists - output_expired - output_not_available - content_filtered - image_generation_failed - reference_media_invalid - reference_media_cap_reached - reference_fetch_failed - unsupported_auth_method - insufficient_scope - uploads_expired - provider_unknown_error message: type: string description: Human-readable message example: Team available balance is 1.5 credits, generation requires 2.0. param: type: object description: Field name when the error is parameter-scoped example: prompt nullable: true doc_url: type: string description: Documentation link for this error code example: https://docs.aurous-labs.com/errors#balance_too_low request_id: type: string description: Echoes Aurous-Request-Id — quote in support tickets example: req_01HXMQ7Z3K8Y2ABCDEFGHJKM required: - type - code - message - doc_url - request_id securitySchemes: api-key: type: apiKey in: header name: X-Api-Key description: Your team API key (starts with `al_live_`). ````