Create signal

POST /api/v2/storefront/signals Registers a signal so it can be deployed and surfaced to buyers. You set the key types at creation, and keyType is immutable afterward. countries lists the ISO 3166-1 alpha-2 countries where the signal may be used, as in AdCP’s SignalDefinition; leave it out for no restriction, and change it later with Update signal. Use access records to control visibility (PUBLIC or PROPRIETARY) and optional per-advertiser pricing.

Request

curl -X POST https://api.apostra.com/api/v2/storefront/signals \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "signalId": "acme_high_value_customers",
    "name": "Acme — High-Value Customers",
    "description": "Top 10% LTV customers, refreshed weekly",
    "keyType": ["rampid", "uid2"],
    "countries": ["US", "GB", "DE"],
    "isLive": false
  }'

{
  "signalId": "acme_auto_intenders",
  "name": "Acme — Auto Intenders",
  "description": "In-market auto shoppers, last 30 days",
  "keyType": ["maid"],
  "countries": ["US"],
  "access": [
    {
      "advertiserId": 88421,
      "visibility": "PROPRIETARY",
      "price": {
        "pricing_option_id": "po_cpm_standard",
        "model": "cpm",
        "cpm": 2.5,
        "currency": "USD"
      }
    }
  ],
  "isLive": true
}

Parameters

Field	Type	Required	Notes
`signalId`	string	Yes	Caller-supplied stable identifier. Pattern `^[\w\-:.]+$`, max 255. Immutable
`name`	string	Yes	Human-readable name (max 255)
`keyType`	string[]	Yes	Identifiers the segment is keyed on. At least one context type (`country`, `region`, `metro`, `topic`, `eidr`, `gracenote`, `isrc`, `gtin`, `rss_guid`, `isbn`, `url`, `url_hash`, `custom`) or identity type (`maid`, `rampid`, `rampid_derived`, `hashed_email`, `hashed_phone`, `id5`, `uid2`, `euid`, `pairid`) — never both classes on one signal. Immutable
`agentId`	string	No	Owning signals agent (for agent-managed signals)
`description`	string	No	What the segment represents (max 5000)
`countries`	string[]	No	ISO 3166-1 alpha-2 country codes where the signal may be used, for example `["US", "GB"]`. At least one code when present; omit for no restriction
`metadata`	object	No	Free-form key/value metadata
`access`	object[]	No	Access records. Each requires `advertiserId` (int64) and `visibility` (`PUBLIC` or `PROPRIETARY`); optional `price`, an AdCP `VendorPricingOption` (see Access records)
`isLive`	boolean	No	Whether the signal is deployed and accepting buys. Default `false`

Response

{
  "signal": {
    "id": 50213,
    "signalId": "acme_high_value_customers",
    "customerId": 1001,
    "adcpAgentId": null,
    "name": "Acme — High-Value Customers",
    "description": "Top 10% LTV customers, refreshed weekly",
    "keyType": ["rampid", "uid2"],
    "countries": ["US", "GB", "DE"],
    "metadata": null,
    "isLive": false,
    "archivedAt": null,
    "createdBy": "agent@acme.example",
    "updatedBy": null,
    "createdAt": "2026-06-06T12:00:00Z",
    "updatedAt": "2026-06-06T12:00:00Z"
  },
  "access": []
}

The numeric id and the string signalId are both returned. Pass signalId to every sibling operation.

Errors

400 VALIDATION_ERROR — missing signalId, name, or keyType; malformed signalId; an empty keyType array; a countries entry that is not an assigned ISO 3166-1 alpha-2 code; a regions field (replaced by countries); a price that is not an AdCP VendorPricingOption; or a keyType array that mixes context types with identity types (a single signal must be one class or the other — see Key types and the privacy boundary).
401 UNAUTHORIZED — missing or invalid bearer token.

See Errors for the full error contract.

Signal tasks

All signal operations

Signal overview

Fields, lifecycle, and concepts

Update signal

Change metadata and access records

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Request

Parameters

Response

Errors

Signal tasks

Signal overview

Update signal

​Request

​Parameters

​Response

​Errors

​Related

Signal tasks

Signal overview

Update signal

Request

Parameters

Response

Errors

Related