Gajo A/B Templates API

Pro. Reusable, abstract split tests (variant names and percentages only, no URLs).

GitHub OpenAPI

Operations 6

GET /ab-templates List A/B templates #
POST /ab-templates Create an A/B template #
GET /ab-templates/{name} Get an A/B template #
PUT /ab-templates/{name} Replace an A/B template's variants #
PATCH /ab-templates/{name} Rename an A/B template #
DELETE /ab-templates/{name} Delete an A/B template #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/gajo-io:gajo-io-a-b-templates-api"
All apis
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.

Get an API 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 Specification

gajo-io-a-b-templates-api-openapi.yml Raw ↑
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