# Create subscription

Create a subscription binding a channel to a transaction family and a trigger, with an optional scope
filter. Exactly matching an existing configuration returns it unchanged with 200 instead of creating a
duplicate; a new configuration returns 201.

Endpoint: POST /subscriptions
Version: 2.0.0
Security: Auth

## Security:

  - `Auth` (unknown)
    apiKey in header X-Api-Key scopes: api:subscription:write

## Header parameters:

  - `Idempotency-Key` (string, required)
    Case-sensitive opaque key for one mutation intent. Send exactly one header occurrence containing 1 to 128 visible ASCII bytes (0x21..0x7e). Commas are literal data; do not trim, lowercase or require UUID syntax. Reuse the same key for retries, with current authorization checked on every attempt. Repeated header occurrences are rejected.

## Request fields (application/json):

  - `name` (string, required)
    Display name for the notification subscription.
    Example: Transaction Alerts

  - `channel_id` (string, required)
    Unique identifier (UUID).
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `family` (any, required)
    Transaction family this subscription watches. Null selects every supported family.
    Example: evm

  - `trigger` (any, required)
    The trigger as a client sends it, the request form of `SubscriptionTrigger`: exactly one alternative,
each closed to unknown properties. What each kind means is described on `SubscriptionTrigger`.

  - `trigger.kind` (string, required)
    Trigger kind, the discriminator of SubscriptionTriggerInput.
    Enum: "block", "network", "mempool"

  - `trigger.after_blocks` (integer, required)
    Number of blocks to wait after inclusion before notifying. Bounded by the int64 range. Zero reports
an observed inclusion without a finality guarantee.

  - `filters` (object)
    Transaction scope as a client sends it, the request form of `SubscriptionFilters`. Omitted
properties mean unrestricted scope; a present array must be nonempty; an unknown property is
rejected. Selected networks must support the subscription, and selected tags must belong to
the project.
    Example: {"chain_gids":["eip155:1","eip155:56"],"address_tag_ids":["550e8400-e29b-41d4-a716-446655440020"]}

  - `filters.chain_gids` (array)
    Restrict matching to these networks. Omit for no network restriction within the family.

  - `filters.address_tag_ids` (array)
    Restrict matching to addresses carrying any of these project tags. Omit for every project address.

  - `is_noise_filtered` (boolean)
    Whether automatic noise filtering applies to candidate activity. Setting this to false
bypasses only noise filtering; project ownership, enabled and active state requirements, and
notification timing still apply.
    Example: true

## Request examples:

  - `Notify 3 blocks after inclusion on selected networks and tags` (unknown)

  - `Notify from the Bitcoin mempool with no scope restriction` (unknown)

## Response 200:

  - `200` (unknown)
    Notification subscription details.

## Response 200 fields (application/json):

  - `item` (object, required)
    Notification subscription that binds a channel to a transaction family, a firing trigger and an optional
scope filter. When trigger is a mempool trigger, family must be bitcoin.
    Example: {"id":"550e8400-e29b-41d4-a716-446655440010","channel_id":"550e8400-e29b-41d4-a716-446655440001","name":"Customer payments","family":"evm","trigger":{"kind":"block","after_blocks":3},"filters":{"chain…

  - `item.id` (string, required)
    Unique identifier (UUID).
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `item.name` (string, required)
    Display name for the notification subscription.
    Example: Transaction Alerts

  - `item.family` (any, required)
    Transaction family this subscription watches. Null selects every supported family.
    Example: evm

  - `item.trigger` (any, required)
    Condition under which the subscription notifies, exactly one alternative. A block trigger fires a fixed
number of blocks after inclusion; a network trigger fires at the network's own confirmation policy; a
mempool trigger fires before inclusion and requires family bitcoin. A subscription cannot switch between
trigger kinds once created.

  - `item.trigger.kind` (string, required)
    Trigger kind, the discriminator of SubscriptionTrigger.
    Enum: "block", "network", "mempool"

  - `item.trigger.after_blocks` (integer, required)
    Number of blocks to wait after inclusion before notifying. Bounded by the int64 range. Zero reports
an observed inclusion without a finality guarantee. Sent notifications are not automatically
corrected after a withdrawal or replacement.

  - `item.filters` (object, required)
    Transaction scope within the subscribed family. Omitted properties mean unrestricted scope;
a present array must be nonempty. Selected networks must support the subscription, and
selected tags must belong to the project.
    Example: {"chain_gids":["eip155:1","eip155:56"],"address_tag_ids":["550e8400-e29b-41d4-a716-446655440020"]}

  - `item.filters.chain_gids` (array)
    Restrict matching to these networks. Omit for no network restriction within the family.

  - `item.filters.address_tag_ids` (array)
    Restrict matching to addresses carrying any of these project tags. Omit for every project address.

  - `item.is_noise_filtered` (boolean, required)
    Whether automatic noise filtering applies to candidate activity. Setting this to false
bypasses only noise filtering; project ownership, enabled and active state requirements, and
notification timing still apply.
    Example: true

  - `item.enabled` (boolean, required)
    Whether this subscription is active.

  - `item.created_at` (string, required)
    Timestamp when the resource was created.
    Example: 2024-01-15T10:30:00Z

  - `item.updated_at` (string, required)
    Timestamp when the resource was last updated.
    Example: 2024-01-15T10:30:00Z

  - `references` (object, required)
    Related objects included in the response, keyed by ID.

  - `references.channels` (object)
    Map of notification channels indexed by their UUID ID.

  - `references.address_tags` (object)
    Map of address tags selected by filters, indexed by their UUID ID.

  - `references.blockchains` (object)
    Map of blockchains selected by filters, indexed by their CAIP-2 Chain GID.

## Response 201:

  - `201` (unknown)
    Notification subscription details.

## Response 201 fields (application/json):

  - `item` (object, required)
    Notification subscription that binds a channel to a transaction family, a firing trigger and an optional
scope filter. When trigger is a mempool trigger, family must be bitcoin.
    Example: {"id":"550e8400-e29b-41d4-a716-446655440010","channel_id":"550e8400-e29b-41d4-a716-446655440001","name":"Customer payments","family":"evm","trigger":{"kind":"block","after_blocks":3},"filters":{"chain…

  - `item.id` (string, required)
    Unique identifier (UUID).
    Example: 550e8400-e29b-41d4-a716-446655440000

  - `item.name` (string, required)
    Display name for the notification subscription.
    Example: Transaction Alerts

  - `item.family` (any, required)
    Transaction family this subscription watches. Null selects every supported family.
    Example: evm

  - `item.trigger` (any, required)
    Condition under which the subscription notifies, exactly one alternative. A block trigger fires a fixed
number of blocks after inclusion; a network trigger fires at the network's own confirmation policy; a
mempool trigger fires before inclusion and requires family bitcoin. A subscription cannot switch between
trigger kinds once created.

  - `item.trigger.kind` (string, required)
    Trigger kind, the discriminator of SubscriptionTrigger.
    Enum: "block", "network", "mempool"

  - `item.trigger.after_blocks` (integer, required)
    Number of blocks to wait after inclusion before notifying. Bounded by the int64 range. Zero reports
an observed inclusion without a finality guarantee. Sent notifications are not automatically
corrected after a withdrawal or replacement.

  - `item.filters` (object, required)
    Transaction scope within the subscribed family. Omitted properties mean unrestricted scope;
a present array must be nonempty. Selected networks must support the subscription, and
selected tags must belong to the project.
    Example: {"chain_gids":["eip155:1","eip155:56"],"address_tag_ids":["550e8400-e29b-41d4-a716-446655440020"]}

  - `item.filters.chain_gids` (array)
    Restrict matching to these networks. Omit for no network restriction within the family.

  - `item.filters.address_tag_ids` (array)
    Restrict matching to addresses carrying any of these project tags. Omit for every project address.

  - `item.is_noise_filtered` (boolean, required)
    Whether automatic noise filtering applies to candidate activity. Setting this to false
bypasses only noise filtering; project ownership, enabled and active state requirements, and
notification timing still apply.
    Example: true

  - `item.enabled` (boolean, required)
    Whether this subscription is active.

  - `item.created_at` (string, required)
    Timestamp when the resource was created.
    Example: 2024-01-15T10:30:00Z

  - `item.updated_at` (string, required)
    Timestamp when the resource was last updated.
    Example: 2024-01-15T10:30:00Z

  - `references` (object, required)
    Related objects included in the response, keyed by ID.

  - `references.channels` (object)
    Map of notification channels indexed by their UUID ID.

  - `references.address_tags` (object)
    Map of address tags selected by filters, indexed by their UUID ID.

  - `references.blockchains` (object)
    Map of blockchains selected by filters, indexed by their CAIP-2 Chain GID.

## Response 400:

  - `400` (unknown)
    Bad request (e.g., missing or invalid fields). Invalid text may be reported as address.label_invalid, address.meta_invalid, public_key.label_invalid, invoice.comment_invalid, invoice.metadata_invalid.

## Response 400 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

  - `fields` (array)
    List of invalid fields in the request.

  - `fields.name` (string, required)
    The name of the invalid field.
    Example: max_len

  - `fields.reason` (string, required)
    Why this field is invalid.
    Example: 32

## Response 401:

  - `401` (unknown)
    Missing or invalid authentication credentials.

## Response 401 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 403:

  - `403` (unknown)
    Insufficient permissions.

## Response 403 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 404:

  - `404` (unknown)
    Requested resource does not exist.

## Response 404 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 409:

  - `409` (unknown)
    Request conflicts with the current resource state.

## Response 409 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 429:

  - `429` (unknown)
    Resource quota exceeded. The response includes the effective limit for this scope. The applicable code and limit depend on the operation; examples illustrate different limits.

## Response 429 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable code identifying the exhausted resource quota. The code is always
supplied by the service; clients branch on it instead of the human-readable detail.
    Example: address.quota_exceeded

  - `max` (integer, required)
    Effective maximum for this resource in the caller's scope. Zero prohibits new admissions;
it does not disable resources already held. This is the configured limit, not current usage.
    Example: 100

## Response 503:

  - `503` (unknown)
    The operation is temporarily unavailable. Please try again later.

## Response 503 fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response default:

  - `default` (unknown)
    Unexpected error.

## Response default fields (application/problem+json):

  - `type` (string, required)
    A URI that identifies the error type.
    Example: https://docs.vilna.io/apis/errors#internal-error

  - `title` (string, required)
    A short summary of the error type.
Use `detail` for information specific to this occurrence.
    Example: Bad Request

  - `status` (integer, required)
    The HTTP status code for this error.
Matches the status code of the HTTP response.
    Example: 400

  - `detail` (string)
    A human-readable explanation of what went wrong in this specific case.
May be localized.
    Example: The address is already assigned to another invoice

  - `instance` (string)
    A URI that identifies this specific error occurrence.
Include this value when contacting support.
    Example: /traces/0123456789abcdef0123456789abcdef

  - `code` (string, required)
    Stable machine-readable error code for programmatic error handling. Unlike the HTTP `status` or free-form `detail`, this code is guaranteed not to change between versions for a given error condition, so it is safe to branch on in client code. Defaults to `unspecified` when the server has not assigned a specific code.
    Example: blockchain.not_found

## Response 400 examples:

  - `The request body contains malformed JSON` (unknown)

## Response 401 examples:

  - `The API service refused authentication` (unknown)

## Response 403 examples:

  - `The API key lacks the required permission` (unknown)

## Response 404 examples:

  - `The address does not exist in this project` (unknown)

  - `The invoice does not exist in this project` (unknown)

## Response 409 examples:

  - `The address already has an active invoice` (unknown)

  - `The address cannot be deleted while in use` (unknown)

  - `A v1-created subscription rejects trigger, filter or noise changes` (unknown)

  - `The notification already has a manual attempt queued or in flight` (unknown)

  - `Retention has cleared the content, so there is nothing to resend` (unknown)

  - `The notification is a channel test` (unknown)

## Response 429 examples:

  - `The project has reached its address quota` (unknown)

  - `A zero effective limit prohibits new resources` (unknown)

## Response 503 examples:

  - `The operation cannot be completed at present` (unknown)