> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pictify.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Experiments
> Manage A/B tests, smart links, and scheduled variants via API
# Experiments
Create and manage experiments to test image variants. Supports A/B tests with Thompson Sampling, smart links with condition-based routing, and scheduled variants.
For experiment types, lifecycle, and tracking details, see [Experiments Concept](/concepts/experiments).
## Endpoints
| Method | Endpoint | Description |
| -------- | --------------------------------- | -------------------------------------------------------------------- |
| `GET` | `/experiments/api` | [List experiments](/api-reference/endpoints/experiments/list) |
| `POST` | `/experiments/api` | [Create experiment](/api-reference/endpoints/experiments/create) |
| `GET` | `/experiments/api/{uid}` | [Get experiment](/api-reference/endpoints/experiments/get) |
| `PUT` | `/experiments/api/{uid}` | [Update experiment](/api-reference/endpoints/experiments/update) |
| `DELETE` | `/experiments/api/{uid}` | [Delete experiment](/api-reference/endpoints/experiments/delete) |
| `POST` | `/experiments/api/{uid}/start` | [Start experiment](/api-reference/endpoints/experiments/start) |
| `POST` | `/experiments/api/{uid}/pause` | [Pause experiment](/api-reference/endpoints/experiments/pause) |
| `POST` | `/experiments/api/{uid}/complete` | [Complete experiment](/api-reference/endpoints/experiments/complete) |
| `GET` | `/experiments/api/quota` | [Check quota](/api-reference/endpoints/experiments/quota) |
| `POST` | `/s/events` | [Track events](/api-reference/endpoints/experiments/events) |
| `GET` | `/s/{slug}/click` | [Click redirect](/api-reference/endpoints/experiments/click) |
| `GET` | `/s/{slug}/pixel.gif` | [Tracking pixel](/api-reference/endpoints/experiments/pixel) |
## Editable Fields by Status
| Status | Editable Fields |
| ------------------ | ---------------------------------------------------------------------------- |
| `draft` / `paused` | All fields |
| `running` | `name`, `confidenceThreshold`, `minimumRunDays`, `goalConfig.destinationUrl` |
| `completed` | `name` only |
Variant weights must sum to exactly **10,000** (basis points). A 50/50 split uses weights of 5000 and 5000.
## Experiment Status
| Status | Description |
| ----------- | --------------------------------------------- |
| `draft` | Created but not started |
| `running` | Actively serving variants and tracking events |
| `paused` | Temporarily stopped, can be restarted |
| `completed` | Finished with a declared winner |
| `archived` | Soft-deleted |
## Slug Requirements
| Rule | Details |
| ---------- | --------------------------------------------------------------------- |
| Length | 3-60 characters |
| Format | Lowercase alphanumeric and hyphens |
| Pattern | Must start and end with alphanumeric |
| Uniqueness | Must be unique among active experiments |
| Reserved | `events`, `api`, `admin`, `health`, `status`, `pixel`, `track`, `sdk` |
## Best Practices
1. **Use descriptive slugs** that identify the test (e.g., `email-banner-cta-test`)
2. **Start with a 50/50 split** before enabling auto-optimization
3. **Set clear goals** -- use `click_through` when you want to measure engagement
4. **Check your quota** before creating experiments with `GET /experiments/api/quota`
5. **Always send a write key** with event tracking to prevent data tampering
## OpenAPI
````yaml get /experiments/api
openapi: 3.1.0
info:
title: Pictify API
version: 1.0.0
description: |
Generate images, GIFs, and PDFs from HTML templates programmatically.
## Authentication
All API requests require a Bearer token in the Authorization header:
```
Authorization: Bearer pk_live_your_api_key
```
## Rate Limits
- Free: 60 requests/minute
- Pro: 300 requests/minute
- Business: 1,000 requests/minute
Rate limit headers are included in all responses.
contact:
email: support@pictify.io
url: https://pictify.io
license:
name: MIT
servers:
- url: https://api.pictify.io
description: Production
security:
- bearerAuth: []
tags:
- name: Images
description: Image generation endpoints
- name: GIFs
description: GIF generation and capture
- name: PDFs
description: PDF generation
- name: Templates
description: Template management
- name: Batch
description: Batch rendering operations
- name: Experiments
description: A/B testing, smart links, and scheduled variant experiments
- name: Webhooks
description: Webhook subscription management
- name: Bindings
description: Data binding for auto-rendering
paths:
/experiments/api:
get:
tags:
- Experiments
summary: List experiments
description: Retrieve all experiments for the authenticated team.
operationId: listExperiments
parameters:
- name: type
in: query
schema:
type: string
enum:
- ab_test
- smart_link
- scheduled
description: Filter by experiment type
- name: status
in: query
schema:
type: string
enum:
- draft
- running
- paused
- completed
description: Filter by status
- name: page
in: query
schema:
type: integer
minimum: 1
default: 1
description: Page number
- name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: Number of results per page
responses:
'200':
description: List of experiments
content:
application/json:
schema:
type: object
properties:
experiments:
type: array
items:
$ref: '#/components/schemas/Experiment'
total:
type: integer
description: Total number of experiments matching filters
page:
type: integer
limit:
type: integer
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
Experiment:
type: object
required:
- uid
- slug
- type
- name
- status
- variants
- createdAt
- updatedAt
properties:
uid:
type: string
example: exp_abc123
slug:
type: string
description: >-
URL-friendly identifier (3-60 chars, lowercase alphanumeric +
hyphens)
example: homepage-hero-test
type:
type: string
enum:
- ab_test
- smart_link
- scheduled
description: Experiment type
name:
type: string
description: Experiment name
example: Homepage Hero A/B Test
status:
type: string
enum:
- draft
- running
- paused
- completed
- archived
description: Current experiment status
templateUid:
type: string
description: Default template UID for variants
example: tmpl_xyz789
variants:
type: array
items:
$ref: '#/components/schemas/ExperimentVariant'
goalConfig:
$ref: '#/components/schemas/GoalConfig'
banditConfig:
$ref: '#/components/schemas/BanditConfig'
hypothesis:
type: string
maxLength: 500
description: Test hypothesis
minimumSampleSize:
type: integer
default: 1000
confidenceThreshold:
type: number
default: 0.95
minimumRunDays:
type: integer
default: 7
winnerVariantId:
type: string
nullable: true
description: Winning variant ID (set when experiment is completed)
winnerDeclaredAt:
type: string
format: date-time
nullable: true
fallbackImageUrl:
type: string
format: uri
description: Image URL to serve after experiment ends
outputConfig:
type: object
properties:
format:
type: string
enum:
- png
- jpeg
- webp
default: png
quality:
type: number
default: 90
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
Error:
type: object
required:
- type
- title
- status
properties:
type:
type: string
format: uri
description: Link to error documentation
example: https://docs.pictify.io/errors/invalid-api-key
title:
type: string
description: Short error title
example: Invalid API Key
status:
type: integer
description: HTTP status code
example: 401
detail:
type: string
description: Detailed error message
example: The provided API key is invalid or has been revoked.
instance:
type: string
description: Request path that caused the error
example: /image
ExperimentVariant:
type: object
required:
- id
- weight
properties:
id:
type: string
description: Unique variant identifier
pattern: ^[a-zA-Z0-9_-]+$
example: variant-a
name:
type: string
example: New Design
templateUid:
type: string
description: Override template for this variant
variables:
type: object
additionalProperties: true
description: Template variables for this variant
weight:
type: integer
minimum: 0
maximum: 10000
description: >-
Traffic weight in basis points. All variant weights must sum to
exactly 10000.
example: 5000
isDefault:
type: boolean
default: false
conditions:
$ref: '#/components/schemas/ConditionTree'
schedule:
$ref: '#/components/schemas/VariantSchedule'
impressions:
type: integer
readOnly: true
description: Total impressions for this variant
clicks:
type: integer
readOnly: true
description: Total clicks for this variant
GoalConfig:
type: object
properties:
type:
type: string
enum:
- impressions_only
- click_through
default: impressions_only
destinationUrl:
type: string
format: uri
description: Redirect URL for click-through goals
BanditConfig:
type: object
description: Auto-optimization settings (A/B tests only)
properties:
enabled:
type: boolean
default: false
algorithm:
type: string
enum:
- thompson_sampling
default: thompson_sampling
warmupImpressions:
type: integer
default: 50
description: Minimum impressions before optimization begins
recomputeIntervalMinutes:
type: integer
default: 15
ConditionTree:
type: object
description: Nested AND/OR condition tree for smart link routing (max depth 3)
properties:
type:
type: string
enum:
- group
- rule
operator:
type: string
enum:
- AND
- OR
description: Logic operator for group nodes
children:
type: array
items:
$ref: '#/components/schemas/ConditionTree'
property:
type: string
description: Context property to evaluate (for rule nodes)
ruleOperator:
type: string
enum:
- equals
- not_equals
- contains
- not_contains
- starts_with
- ends_with
- gt
- lt
- gte
- lte
description: Comparison operator for rule nodes
value:
description: Value to compare against
VariantSchedule:
type: object
description: Time-based activation schedule for scheduled variants
properties:
startAt:
type: string
format: date-time
endAt:
type: string
format: date-time
recurrence:
type: object
properties:
type:
type: string
enum:
- none
- daily
- weekly
- cron
default: none
cronExpression:
type: string
description: Cron expression (when type is cron)
timezone:
type: string
default: UTC
example: America/New_York
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key obtained from the Pictify dashboard
````