> ## Documentation Index
> Fetch the complete documentation index at: https://learn.biq.li/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a tracking pixel
> Create a provider tracking pixel or a custom tracking-code configuration.
`POST /v1/tracking-pixel` creates a reusable tracking configuration in the
workspace bound to your API key. It requires **Tracking pixels: Write**
(`tracking_pixels.create`).
Choose one of the two request types in the API playground. Provider pixels and
custom code deliberately expose different fields.
`custom` does not appear in the provider `type` dropdown. Select the
**Custom code** tab above the request fields to create one.
## Create a provider pixel
Provider pixels require `name`, `type`, and `pixel_id`.
```bash theme={null}
curl --request POST \
--url https://biq.li/api/v1/tracking-pixel \
--header 'Authorization: Bearer biqli_your_workspace_api_key' \
--header 'Content-Type: application/json' \
--data '{
"name": "Main Meta pixel",
"type": "facebook",
"pixel_id": "123456789"
}'
```
Supported provider types are:
| Type | Configuration value |
| -------------------- | ------------------------------------------------------------ |
| `facebook` | Meta pixel ID |
| `twitter` | X, formerly Twitter, pixel ID |
| `google-tag-manager` | Google Tag Manager container ID |
| `google-analytics` | Google Analytics measurement ID |
| `adwords` | Google Ads conversion or account ID used by your integration |
| `bing` | Microsoft Advertising UET tag ID |
| `pinterest` | Pinterest tag ID |
| `linkedin` | LinkedIn Insight Tag partner ID |
| `quora` | Quora pixel ID |
| `adroll` | AdRoll advertiser or pixel ID |
| `nexus-segment` | AppNexus or Segment integration ID |
For these types, send the provider value in `pixel_id`. Do not send
`head_code` or `body_code`. Biqli handles the provider integration and stores
both code fields as `null`.
## Create custom code
Use `type: "custom"` only when you need to supply your own tracking snippet.
Provide `head_code`, `body_code`, or both.
```bash theme={null}
curl --request POST \
--url https://biq.li/api/v1/tracking-pixel \
--header 'Authorization: Bearer biqli_your_workspace_api_key' \
--header 'Content-Type: application/json' \
--data '{
"name": "Custom analytics snippet",
"type": "custom",
"head_code": "",
"body_code": ""
}'
```
Do not send `pixel_id` for a custom pixel. Biqli stores it as `null`.
Custom code can execute on pages where the tracking configuration is used.
Only add code that you understand and trust.
## Field rules
| Field | Provider pixel | Custom code |
| ----------- | -------------------------------------- | ------------------------------------ |
| `name` | Required, 3 to 80 characters | Required, 3 to 80 characters |
| `type` | Required provider value from the table | Required and must be `custom` |
| `pixel_id` | Required, maximum 200 characters | Not supported |
| `head_code` | Not supported | Optional, maximum 100,000 characters |
| `body_code` | Not supported | Optional, maximum 100,000 characters |
A custom pixel must contain at least one non-empty code field. Unknown fields
are rejected.
## Response and errors
Success returns `201 Created` with the complete `pixel` resource. Its ID starts
with `biq_pxl_`. Pixel names must be unique inside the workspace.
* `409 pixel_name_taken` means another workspace pixel already uses the name.
* `422 validation_error` means the selected type is invalid, a required field
is missing, or the request mixes provider and custom fields.
* `403 insufficient_scope` means the API key does not have
`tracking_pixels.create`.
## Shared API behavior
Authentication is workspace-scoped; see
[Authentication](/docs/api-reference/authentication). Errors use the standard
envelope and request IDs described in [Errors](/docs/api-reference/errors), and
requests are subject to [Rate limits](/docs/api-reference/rate-limits).
## OpenAPI
````yaml POST /v1/tracking-pixel
openapi: 3.1.0
info:
title: Biqli API
version: 1.0.0
description: Workspace-scoped REST API for Biqli.
servers:
- url: https://biq.li/api
security:
- bearerAuth: []
paths:
/v1/tracking-pixel:
post:
tags:
- Tracking pixels
summary: Create a tracking pixel
description: >-
Creates a tracking pixel in the API key workspace. Requires
tracking_pixels.create.
operationId: pixel.store
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PixelWrite'
responses:
'201':
description: Pixel created.
content:
application/json:
schema:
$ref: '#/components/schemas/PixelResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
$ref: '#/components/responses/Conflict'
'422':
$ref: '#/components/responses/UnprocessableEntity'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/InternalError'
components:
schemas:
PixelWrite:
oneOf:
- title: Provider pixel
type: object
additionalProperties: false
required:
- name
- type
- pixel_id
properties:
name:
type: string
minLength: 3
maxLength: 80
type:
type: string
enum:
- facebook
- twitter
- google-tag-manager
- google-analytics
- adwords
- bing
- pinterest
- linkedin
- quora
- adroll
- nexus-segment
pixel_id:
type: string
minLength: 1
maxLength: 200
description: Provider-issued pixel, tag, or account identifier.
- title: Custom code
type: object
additionalProperties: false
required:
- name
- type
minProperties: 3
description: >-
Provide head_code, body_code, or both. At least one code field must
be non-empty.
properties:
name:
type: string
minLength: 3
maxLength: 80
type:
type: string
const: custom
default: custom
x-default: custom
head_code:
type: string
minLength: 1
maxLength: 100000
description: Custom code inserted in the page head.
body_code:
type: string
minLength: 1
maxLength: 100000
description: Custom code inserted in the page body.
PixelResponse:
type: object
required:
- pixel
- status
properties:
pixel:
$ref: '#/components/schemas/Pixel'
status:
type: string
const: success
Pixel:
type: object
additionalProperties: false
required:
- id
- name
- type
- pixel_id
- head_code
- body_code
- links_count
properties:
id:
type: string
pattern: ^biq_pxl_[0-9A-HJKMNP-TV-Z]{26}$
name:
type: string
type:
type: string
enum:
- facebook
- twitter
- google-tag-manager
- google-analytics
- adwords
- bing
- pinterest
- linkedin
- quora
- adroll
- nexus-segment
- custom
pixel_id:
type:
- string
- 'null'
description: Provider identifier, or null for custom pixels.
head_code:
type:
- string
- 'null'
description: Custom head code, or null for provider pixels.
body_code:
type:
- string
- 'null'
description: Custom body code, or null for provider pixels.
links_count:
type: integer
minimum: 0
created_at:
type:
- string
- 'null'
format: date-time
updated_at:
type:
- string
- 'null'
format: date-time
ApiError:
type: object
required:
- error
- request_id
properties:
error:
type: object
required:
- code
- message
properties:
code:
type: string
enum:
- invalid_token
- insufficient_scope
- upgrade_required
- quota_exceeded
- resource_not_found
- domain_taken
- alias_taken
- external_id_taken
- folder_name_taken
- tag_name_taken
- pixel_name_taken
- biolink_name_taken
- method_not_allowed
- url_blocked
- dns_verification_failed
- validation_error
- rate_limit_exceeded
- internal_server_error
message:
type: string
details:
type: object
additionalProperties: true
request_id:
type: string
description: Request identifier to include when contacting support.
responses:
Unauthorized:
$ref: '#/components/responses/ApiErrorResponse'
description: The workspace API key is missing, invalid, or revoked.
Forbidden:
$ref: '#/components/responses/ApiErrorResponse'
description: >-
The key lacks a required scope, the workspace must upgrade, or its quota
is exhausted.
Conflict:
$ref: '#/components/responses/ApiErrorResponse'
description: >-
A unique alias, external ID, custom domain, or workspace resource name
is already in use.
UnprocessableEntity:
$ref: '#/components/responses/ApiErrorResponse'
description: >-
The payload is invalid, a destination was blocked, or domain DNS
verification is not ready.
RateLimited:
description: The workspace exceeded its plan's API rate limit.
headers:
RateLimit-Policy:
description: Current IETF HTTPAPI quota policy as a structured field.
schema:
type: string
example: '"workspace-api";q=1000;w=60'
RateLimit:
description: Current IETF HTTPAPI service limit as a structured field.
schema:
type: string
example: '"workspace-api";r=0;t=17'
Retry-After:
description: Seconds to wait before retrying the request.
schema:
type: integer
minimum: 0
example: 17
X-RateLimit-Limit:
description: Legacy maximum request count for the current window.
schema:
type: integer
minimum: 1
example: 1000
X-RateLimit-Remaining:
description: Legacy remaining request count.
schema:
type: integer
minimum: 0
example: 0
X-RateLimit-Reset:
description: Legacy reset time as a UTC Unix timestamp.
schema:
type: integer
format: int64
example: 1788126519
X-Biq-Request-Id:
description: Request identifier for support and tracing.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
InternalError:
$ref: '#/components/responses/ApiErrorResponse'
description: The request failed unexpectedly.
ApiErrorResponse:
description: API error.
headers:
X-Biq-Request-Id:
description: Request identifier for support and tracing.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/ApiError'
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Workspace API key
description: A workspace API key beginning with biqli_.
````