Gajo A/B Templates API
Pro. Reusable, abstract split tests (variant names and percentages only, no URLs).
Pro. Reusable, abstract split tests (variant names and percentages only, no URLs).
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/gajo-io:gajo-io-a-b-templates-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Gajo A/B Templates API
version: '1.0'
summary: Short links, QR codes, click analytics, device routing, A/B split links and app deep links.
description: 'Gajo is a URL shortener with QR codes, click analytics, device-based routing, A/B split links, and app deep links with an App Store / Google Play fallback. This REST API creates and manages short links and returns their click analytics.
**Every Gajo account plan includes the core API, including Free (no credit card required).** Create an account, generate a key on the API Keys page, and send it in the `x-api-key` header on every request.
## Plans
| | Free | Basic | Pro |
|---|---|---|---|
| Price | $0, no card | $4.99 / month | $9.99 / month |
| New URLs per month | 50 | 500 | 10,000 |
| API requests per minute | 10 | 30 | 60 |
| Max link lifetime | 60 days | 120 days | Unlimited |
| Generated short code length | 6 characters | 5 characters | 5 characters |
| `GET /urls/{code}/stats` | Click totals + 7-day history | Full analytics: 90-day history, referrers, devices, countries, regions | Full analytics: full history since the link was created |
| Batch shortening, editing destinations, routing rules, route & A/B templates, bindings, app deep links | — | — | Yes |
Operations marked `x-gajo-plan: Pro` return `403` with a message such as `"A Pro plan is required for batch shortening"` on Free and Basic. The monthly URL allowance is shared with links created in the dashboard. Full plan details: gajo.io/pricing.
## Responses
Every response uses the same JSON envelope: `{"success": true|false, "message": string|null, "data": ...}`. On errors `success` is `false` and `message` explains why.
## Rate limits
Each API key may make the plan''s number of requests per 60-second sliding window. Responses carry `X-RateLimit-Limit` and `X-RateLimit-Remaining`; over the limit the API returns `429` with a `Retry-After` header (seconds). `POST /shorten` also returns `429` once the monthly URL allowance is used up.
Guides and examples: gajo.io/docs.'
termsOfService: https://gajo.io/terms
contact:
name: Gajo
url: https://gajo.io
servers:
- url: https://gajo.io/api/v1
description: Production
security:
- ApiKeyAuth: []
tags:
- name: A/B Templates
description: Pro. Reusable, abstract split tests (variant names and percentages only, no URLs).
paths:
/ab-templates:
get:
operationId: listAbTemplates
tags:
- A/B Templates
summary: List A/B templates
description: '**Requires a Pro plan.** Returns your active A/B templates. A/B templates are abstract: variant names and traffic percentages only, no URLs. Concrete destinations are set per link with `POST /urls/{code}/binding`.'
x-gajo-plan: Pro
responses:
'200':
description: Your A/B templates.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/AbTemplateListResult'
example:
success: true
message: null
data:
- name: homepage-test
description: New homepage vs. current
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: null
variants:
- variantName: Control
splitPercentage: 50
priority: 0
- variantName: New-Design
splitPercentage: 50
priority: 1
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Your plan is not Pro (the message names the Pro feature). Also when the account isn't active (not activated yet, or switched off).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A Pro plan is required for A/B templates
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
post:
operationId: createAbTemplate
tags:
- A/B Templates
summary: Create an A/B template
description: '**Requires a Pro plan.** Creates a reusable split test. Variant names must be unique and `splitPercentage` values (each at least 1) must sum to 100. Each click is assigned to a variant at random according to the percentages. A/B templates are abstract: variant names and traffic percentages only, no URLs. Concrete destinations are set per link with `POST /urls/{code}/binding`.'
x-gajo-plan: Pro
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AbTemplateRequest'
example:
name: homepage-test
description: New homepage vs. current
variants:
- variantName: Control
splitPercentage: 50
- variantName: New-Design
splitPercentage: 50
responses:
'200':
description: The new template.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/AbTemplateResult'
example:
success: true
message: A/B template created
data:
name: homepage-test
description: New homepage vs. current
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: null
variants:
- variantName: Control
splitPercentage: 50
priority: 0
- variantName: New-Design
splitPercentage: 50
priority: 1
'400':
description: Invalid request. `message` explains what to fix.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
examples:
badName:
summary: Invalid template name
value:
success: false
message: Template name must be 2-100 characters, alphanumeric, hyphens, and underscores only
data: null
noVariants:
summary: Empty variants array
value:
success: false
message: At least one variant is required
data: null
badSplit:
summary: Percentages do not sum to 100
value:
success: false
message: 'Split percentages must sum to 100 (currently: 90)'
data: null
duplicate:
summary: Repeated variant name
value:
success: false
message: Duplicate variant names are not allowed
data: null
lowSplit:
summary: Percentage below 1
value:
success: false
message: Split percentage must be at least 1
data: null
exists:
summary: Name already used
value:
success: false
message: An A/B template named 'homepage-test' already exists
data: null
invalidJson:
summary: Malformed body or missing required field
value:
success: false
message: Invalid JSON format in request. Missing url or required field.
data: null
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Your plan is not Pro (the message names the Pro feature). Also when the account isn't active (not activated yet, or switched off).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A Pro plan is required for A/B templates
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
/ab-templates/{name}:
parameters:
- $ref: '#/components/parameters/TemplateName'
get:
operationId: getAbTemplate
tags:
- A/B Templates
summary: Get an A/B template
description: '**Requires a Pro plan.** Returns one A/B template by name.'
x-gajo-plan: Pro
responses:
'200':
description: The template.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/AbTemplateResult'
example:
success: true
message: null
data:
name: homepage-test
description: New homepage vs. current
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: null
variants:
- variantName: Control
splitPercentage: 50
priority: 0
- variantName: New-Design
splitPercentage: 50
priority: 1
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Your plan is not Pro (the message names the Pro feature). Also when the account isn't active (not activated yet, or switched off).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A Pro plan is required for A/B templates
'404':
description: No A/B template with this name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A/B template not found
data: null
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
put:
operationId: updateAbTemplate
tags:
- A/B Templates
summary: Replace an A/B template's variants
description: '**Requires a Pro plan.** Replaces the template''s description and full list of variants. The body uses the same shape as create; its `name` must be present but is not used to rename (use `PATCH`). Omitting `description` clears it. Links bound to the template pick up the new split immediately; a binding needs an endpoint for every variant, so rebind links after adding or renaming variants.'
x-gajo-plan: Pro
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/AbTemplateRequest'
example:
name: homepage-test
description: Shift traffic to the new design
variants:
- variantName: Control
splitPercentage: 20
- variantName: New-Design
splitPercentage: 80
responses:
'200':
description: The updated template.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/AbTemplateResult'
example:
success: true
message: A/B template updated
data:
name: homepage-test
description: Shift traffic to the new design
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: '2026-10-08T09:15:00.250Z'
variants:
- variantName: Control
splitPercentage: 20
priority: 0
- variantName: New-Design
splitPercentage: 80
priority: 1
'400':
description: Invalid request. `message` explains what to fix.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
examples:
noVariants:
summary: Empty variants array
value:
success: false
message: At least one variant is required
data: null
badSplit:
summary: Percentages do not sum to 100
value:
success: false
message: 'Split percentages must sum to 100 (currently: 90)'
data: null
duplicate:
summary: Repeated variant name
value:
success: false
message: Duplicate variant names are not allowed
data: null
lowSplit:
summary: Percentage below 1
value:
success: false
message: Split percentage must be at least 1
data: null
invalidJson:
summary: Malformed body or missing required field
value:
success: false
message: Invalid JSON format in request. Missing url or required field.
data: null
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Your plan is not Pro (the message names the Pro feature). Also when the account isn't active (not activated yet, or switched off).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A Pro plan is required for A/B templates
'404':
description: No A/B template with this name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A/B template 'homepage-test' not found
data: null
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
patch:
operationId: renameAbTemplate
tags:
- A/B Templates
summary: Rename an A/B template
description: '**Requires a Pro plan.** Renames the template. Existing bindings keep working.'
x-gajo-plan: Pro
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RenameTemplateRequest'
example:
newName: homepage-test-q4
responses:
'200':
description: The renamed template.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/AbTemplateResult'
example:
success: true
message: A/B template renamed
data:
name: homepage-test-q4
description: New homepage vs. current
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: '2026-10-08T09:15:00.250Z'
variants:
- variantName: Control
splitPercentage: 50
priority: 0
- variantName: New-Design
splitPercentage: 50
priority: 1
'400':
description: Invalid request. `message` explains what to fix.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
examples:
badName:
summary: Invalid template name
value:
success: false
message: Template name must be 2-100 characters, alphanumeric, hyphens, and underscores only
data: null
exists:
summary: Name already used
value:
success: false
message: An A/B template named 'homepage-test-q4' already exists
data: null
invalidJson:
summary: Malformed body or missing required field
value:
success: false
message: Invalid JSON format in request. Missing url or required field.
data: null
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Your plan is not Pro (the message names the Pro feature). Also when the account isn't active (not activated yet, or switched off).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A Pro plan is required for A/B templates
'404':
description: No A/B template with this name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A/B template 'homepage-test' not found
data: null
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
delete:
operationId: deleteAbTemplate
tags:
- A/B Templates
summary: Delete an A/B template
description: '**Requires a Pro plan.** Deletes the template. Links bound to it stop splitting traffic and fall back to their original destination. The name can be used again right away.'
x-gajo-plan: Pro
responses:
'200':
description: The template was deleted.
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/MessageResult'
example:
success: true
message: A/B template deleted
data: null
'401':
$ref: '#/components/responses/Unauthorized'
'403':
description: Your plan is not Pro (the message names the Pro feature). Also when the account isn't active (not activated yet, or switched off).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A Pro plan is required for A/B templates
'404':
description: No A/B template with this name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: A/B template 'homepage-test' not found
data: null
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
components:
schemas:
RenameTemplateRequest:
type: object
required:
- newName
properties:
newName:
type: string
pattern: ^[A-Za-z0-9_-]{2,100}$
description: '2-100 characters: letters, digits, hyphens and underscores. Unique per account.'
MessageResult:
description: Success envelope with a confirmation message and no payload.
allOf:
- $ref: '#/components/schemas/ApiResult'
- type: object
required:
- message
properties:
success:
const: true
message:
type: string
data:
type: 'null'
AbTemplateRequest:
type: object
required:
- name
- variants
properties:
name:
type: string
pattern: ^[A-Za-z0-9_-]{2,100}$
description: '2-100 characters: letters, digits, hyphens and underscores. Unique per account.'
description:
type:
- string
- 'null'
description: Optional note. Omitting it on update clears it.
variants:
type: array
minItems: 1
description: Variants with unique names; `splitPercentage` values must sum to 100.
items:
type: object
required:
- variantName
- splitPercentage
properties:
variantName:
type: string
minLength: 1
splitPercentage:
type: integer
minimum: 1
maximum: 100
AbTemplateResult:
description: Envelope with one A/B template.
allOf:
- $ref: '#/components/schemas/ApiResult'
- type: object
required:
- data
properties:
success:
const: true
data:
$ref: '#/components/schemas/AbTemplate'
ApiResult:
type: object
description: Envelope shared by every response.
required:
- success
properties:
success:
type: boolean
description: '`true` when the request succeeded.'
message:
type:
- string
- 'null'
description: Human-readable status or error message. Often `null` on reads.
data:
description: Operation-specific payload; `null` or absent when there is nothing to return.
ErrorResult:
type: object
description: Error envelope. `success` is always `false` and `message` explains the problem.
required:
- success
- message
properties:
success:
const: false
message:
type: string
data:
type: 'null'
description: Always `null` (or absent) on errors.
AbTemplateListResult:
description: Envelope with A/B templates.
allOf:
- $ref: '#/components/schemas/ApiResult'
- type: object
required:
- data
properties:
success:
const: true
data:
type: array
items:
$ref: '#/components/schemas/AbTemplate'
AbTemplate:
type: object
description: 'An abstract A/B split template: variant names and percentages only, no URLs.'
required:
- name
- description
- active
- createdDate
- updatedDate
- variants
properties:
name:
type: string
description:
type:
- string
- 'null'
active:
type: boolean
createdDate:
type: string
format: date-time
updatedDate:
type:
- string
- 'null'
format: date-time
variants:
type: array
items:
type: object
required:
- variantName
- splitPercentage
- priority
properties:
variantName:
type: string
splitPercentage:
type: integer
minimum: 1
maximum: 100
priority:
type: integer
minimum: 0
description: Position in the template (0-based, request order).
headers:
X-RateLimit-Remaining:
description: Requests left in the current 60-second window.
schema:
type: integer
minimum: 0
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
minimum: 1
X-RateLimit-Limit:
description: Requests allowed per 60-second sliding window for your plan (10 Free, 30 Basic, 60 Pro).
schema:
type: integer
minimum: 1
parameters:
TemplateName:
name: name
in: path
required: true
description: Template name.
schema:
type: string
pattern: ^[A-Za-z0-9_-]{2,100}$
responses:
RateLimited:
description: Per-minute rate limit exceeded. Wait `Retry-After` seconds.
headers:
Retry-After:
$ref: '#/components/headers/Retry-After'
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: Rate limit exceeded. Please try again later.
Unauthorized:
description: The `x-api-key` header is missing, or the key is unknown or revoked.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
examples:
missingKey:
summary: No x-api-key header
value:
success: false
message: Missing x-api-key header
invalidKey:
summary: Unknown or revoked key
value:
success: false
message: Invalid API key
ServerError:
description: Unexpected server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
examples:
internal:
summary: Unexpected error
value:
success: false
message: Internal server error
data: null
internalShort:
summary: Missing record
value:
success: false
message: Internal error
data: null
headers:
X-RateLimit-Limit:
$ref: '#/components/headers/X-RateLimit-Limit'
X-RateLimit-Remaining:
$ref: '#/components/headers/X-RateLimit-Remaining'
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
description: Your Gajo API key. Generate one on the API Keys page of your account (https://gajo.io/account/keys).
externalDocs:
description: Gajo API documentation
url: https://gajo.io/docs