Gajo Bindings API

Pro. Attach a route or A/B template to a link and supply the concrete destination for each slot, including app deep links with store fallbacks.

GitHub OpenAPI

Operations 3

GET /urls/{code}/binding Get a link's binding #
POST /urls/{code}/binding Bind a link to a template #
DELETE /urls/{code}/binding Remove a link's binding #

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-bindings-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-bindings-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: Gajo Bindings 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: Bindings
  description: Pro. Attach a route or A/B template to a link and supply the concrete destination for each slot, including app deep links with store fallbacks.
paths:
  /urls/{code}/binding:
    parameters:
    - $ref: '#/components/parameters/ShortCode'
    get:
      operationId: getUrlBinding
      tags:
      - Bindings
      summary: Get a link's binding
      description: '**Requires a Pro plan.** Returns the link''s template binding and its endpoints, or `{"shortCode": ..., "bound": false}` when the link is not bound.'
      x-gajo-plan: Pro
      responses:
        '200':
          description: The binding.
          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/BindingResult'
              examples:
                bound:
                  summary: Bound to a route template
                  value:
                    success: true
                    message: null
                    data:
                      shortCode: Hn7Kp
                      bound: true
                      routingType: Device
                      templateName: app-store-router
                      routeTemplateId: 17
                      abTemplateId: null
                      createdDate: '2026-10-07T14:03:11.482Z'
                      endpoints:
                      - slotKey: IOS
                        targetType: Url
                        targetUrl: myapp://product/42
                        fallbackUrl: https://apps.apple.com/app/example/id123456789
                        routeTemplateName: null
                        routeTemplateId: null
                        endpointName: null
                      - slotKey: Android
                        targetType: Url
                        targetUrl: myapp://product/42
                        fallbackUrl: https://play.google.com/store/apps/details?id=com.example.app
                        routeTemplateName: null
                        routeTemplateId: null
                        endpointName: null
                      - slotKey: Default
                        targetType: Url
                        targetUrl: https://example.com/product/42
                        fallbackUrl: null
                        routeTemplateName: null
                        routeTemplateId: null
                        endpointName: null
                unbound:
                  summary: Not bound
                  value:
                    success: true
                    message: null
                    data:
                      shortCode: Hn7Kp
                      bound: false
        '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 template bindings
        '404':
          description: No link with this code exists on your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
              example:
                success: false
                message: URL 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'
    post:
      operationId: bindUrl
      tags:
      - Bindings
      summary: Bind a link to a template
      description: '**Requires a Pro plan.** Attaches one route template (`templateType: Device`) or A/B template (`templateType: AbTest`) to the link and supplies a concrete destination for each slot. A link has at most one binding; binding again replaces it. Device bindings need an endpoint for every slot in the route template, unless a `Default` endpoint is included. A/B bindings need an endpoint for every variant. Endpoint `targetUrl`s may be app deep links (custom schemes) with a web `fallbackUrl`, such as the App Store or Google Play listing, used when the app is not installed. Takes effect within a minute.'
      x-gajo-plan: Pro
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindRequest'
            examples:
              device:
                summary: Device routing with deep links and store fallbacks
                value:
                  templateType: Device
                  templateName: app-store-router
                  endpoints:
                  - slotKey: IOS
                    targetUrl: myapp://product/42
                    fallbackUrl: https://apps.apple.com/app/example/id123456789
                  - slotKey: Android
                    targetUrl: myapp://product/42
                    fallbackUrl: https://play.google.com/store/apps/details?id=com.example.app
                  - slotKey: Default
                    targetUrl: https://example.com/product/42
              abTest:
                summary: A/B split
                value:
                  templateType: AbTest
                  templateName: homepage-test
                  endpoints:
                  - slotKey: Control
                    targetUrl: https://example.com
                  - slotKey: New-Design
                    targetUrl: https://example.com/v2
              abChained:
                summary: A/B split where one variant routes by device
                value:
                  templateType: AbTest
                  templateName: homepage-test
                  endpoints:
                  - slotKey: Control
                    targetType: RouteTemplate
                    routeTemplateName: app-store-router
                  - slotKey: Control:IOS
                    targetUrl: https://apps.apple.com/app/example/id123456789
                  - slotKey: Control:Default
                    targetUrl: https://example.com
                  - slotKey: New-Design
                    targetUrl: https://example.com/v2
      responses:
        '200':
          description: The new binding.
          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/BindingCreatedResult'
              examples:
                device:
                  summary: Route template with deep links
                  value:
                    success: true
                    message: URL bound to Device template 'app-store-router'
                    data:
                      shortCode: Hn7Kp
                      routingType: Device
                      templateName: app-store-router
                      endpoints:
                      - slotKey: IOS
                        targetType: Url
                        targetUrl: myapp://product/42
                        fallbackUrl: https://apps.apple.com/app/example/id123456789
                        routeTemplateName: null
                        routeTemplateId: null
                        endpointName: null
                      - slotKey: Android
                        targetType: Url
                        targetUrl: myapp://product/42
                        fallbackUrl: https://play.google.com/store/apps/details?id=com.example.app
                        routeTemplateName: null
                        routeTemplateId: null
                        endpointName: null
                      - slotKey: Default
                        targetType: Url
                        targetUrl: https://example.com/product/42
                        fallbackUrl: null
                        routeTemplateName: null
                        routeTemplateId: null
                        endpointName: null
                abTest:
                  summary: A/B template
                  value:
                    success: true
                    message: URL bound to AbTest template 'homepage-test'
                    data:
                      shortCode: Hn7Kp
                      routingType: AbTest
                      templateName: homepage-test
                      endpoints:
                      - slotKey: Control
                        targetType: Url
                        targetUrl: https://example.com
                        fallbackUrl: null
                        routeTemplateName: null
                        routeTemplateId: null
                        endpointName: null
                      - slotKey: New-Design
                        targetType: Url
                        targetUrl: https://example.com/v2
                        fallbackUrl: null
                        routeTemplateName: null
                        routeTemplateId: null
                        endpointName: null
        '400':
          description: Invalid request. `message` explains what to fix.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
              examples:
                badType:
                  summary: Unknown templateType
                  value:
                    success: false
                    message: 'Invalid template type: Mobile. Must be Device or AbTest'
                    data: null
                templateMissing:
                  summary: Template not found
                  value:
                    success: false
                    message: Route template 'app-store-router' not found
                    data: null
                badSlot:
                  summary: slotKey not in template
                  value:
                    success: false
                    message: 'Endpoint slot ''Phone'' does not match any rule in the route template. Expected: IOS, Android, Default'
                    data: null
                missingSlots:
                  summary: Slots not covered
                  value:
                    success: false
                    message: 'Missing endpoints for: Android. Either provide all slots or include a Default endpoint.'
                    data: null
                missingVariants:
                  summary: Variants not covered
                  value:
                    success: false
                    message: 'Missing endpoints for variants: New-Design'
                    data: null
                fallbackWithoutDeepLink:
                  summary: fallbackUrl on a web destination
                  value:
                    success: false
                    message: Endpoint 'Default' has a fallback URL but its destination is not an app deep link
                    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 template bindings
        '404':
          description: No link with this code exists on your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
              example:
                success: false
                message: URL 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: unbindUrl
      tags:
      - Bindings
      summary: Remove a link's binding
      description: '**Requires a Pro plan.** Removes the link''s template binding and endpoints. The link returns to its per-URL routing rules, if any, or its original destination. Succeeds even when the link has no binding.'
      x-gajo-plan: Pro
      responses:
        '200':
          description: The binding was removed.
          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: URL routing binding removed
                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 template bindings
        '404':
          description: No link with this code exists on your account.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResult'
              example:
                success: false
                message: URL 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:
    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.
    BindingResult:
      description: Envelope with a link's binding.
      allOf:
      - $ref: '#/components/schemas/ApiResult'
      - type: object
        required:
        - data
        properties:
          success:
            const: true
          data:
            $ref: '#/components/schemas/Binding'
    EndpointTarget:
      type: string
      enum:
      - Url
      - RouteTemplate
      description: '`Url` (default) sends the slot to `targetUrl`. `RouteTemplate` is reserved for chaining an A/B variant to a route template; this is not fully supported yet, so use `Url` targets.'
    BindingCreatedResult:
      description: Envelope with a newly created binding.
      allOf:
      - $ref: '#/components/schemas/ApiResult'
      - type: object
        required:
        - data
        properties:
          success:
            const: true
          data:
            $ref: '#/components/schemas/BindingCreated'
    Endpoint:
      type: object
      description: A concrete destination for one slot of a binding.
      required:
      - slotKey
      - targetType
      - targetUrl
      - fallbackUrl
      - routeTemplateName
      - routeTemplateId
      - endpointName
      properties:
        slotKey:
          type: string
          description: Device slot (Device bindings) or variant name (A/B bindings).
        targetType:
          $ref: '#/components/schemas/EndpointTarget'
        targetUrl:
          type:
          - string
          - 'null'
        fallbackUrl:
          type:
          - string
          - 'null'
          description: Web fallback when `targetUrl` is an app deep link and the app is not installed.
        routeTemplateName:
          type:
          - string
          - 'null'
          description: Name of the chained route template when `targetType` is `RouteTemplate` (`null` otherwise, or if it was deleted).
        routeTemplateId:
          type:
          - integer
          - 'null'
          description: 'Numeric ID of the chained route template when `targetType` is `RouteTemplate`. Deprecated: use `routeTemplateName`.'
          deprecated: true
        endpointName:
          type:
          - string
          - 'null'
          description: Optional label.
    BindingEndpoint:
      type: object
      required:
      - slotKey
      properties:
        slotKey:
          description: For `Device` bindings, one of the template's device slots. For `AbTest` bindings, one of the template's variant names, or `Variant:Device` (e.g. `Control:IOS`) for the device destinations of a variant that chains to a route template.
          anyOf:
          - $ref: '#/components/schemas/DeviceSlot'
          - type: string
            description: A/B variant name
        targetType:
          $ref: '#/components/schemas/EndpointTarget'
          default: Url
        targetUrl:
          type: string
          maxLength: 2048
          description: Required when `targetType` is `Url`. May be an app deep link (custom scheme).
        fallbackUrl:
          type: string
          description: 'Only when `targetUrl` is an app deep link: web URL (e.g. App Store / Google Play listing) used when the app is not installed.'
        routeTemplateName:
          type: string
          description: 'With `targetType: RouteTemplate` (A/B bindings): the route template this variant chains to. Add the variant''s per-device destinations as endpoints keyed `Variant:Device`, covering every slot of the route template or including `Variant:Default`.'
        endpointName:
          type: string
          description: Optional label for this endpoint.
    DeviceSlot:
      type: string
      enum:
      - Android
      - IOS
      - Mobile
      - Tablet
      - Desktop
      - Default
      description: Device slot used by route templates and Device bindings. At redirect time OS-specific slots (`Android`, `IOS`) are matched first, then device classes (`Mobile`, `Tablet`, `Desktop`), then `Default` catches everything else.
    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'
    BindRequest:
      type: object
      required:
      - templateType
      - templateName
      - endpoints
      properties:
        templateType:
          $ref: '#/components/schemas/RoutingType'
          description: '`Device` to bind a route template, `AbTest` to bind an A/B template.'
        templateName:
          type: string
          description: Name of your route template or A/B template.
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/BindingEndpoint'
          description: One endpoint per slot. Device bindings must cover every template slot unless a `Default` endpoint is included; A/B bindings must cover every variant, plus `Variant:Device` endpoints for any variant that chains to a route template.
        flowJson:
          type:
          - string
          - 'null'
          description: Optional layout state for the dashboard's visual Route Builder. API clients can omit it.
    RoutingType:
      type: string
      enum:
      - Device
      - AbTest
      description: '`Device` routes by device class; `AbTest` splits traffic by percentage.'
    Binding:
      type: object
      description: A link's template binding. When `bound` is `false`, only `shortCode` and `bound` are returned.
      required:
      - bound
      properties:
        shortCode:
          type: string
        bound:
          type: boolean
        routingType:
          $ref: '#/components/schemas/RoutingType'
          description: '`Device` (route template) or `AbTest` (A/B template).'
        templateName:
          type:
          - string
          - 'null'
          description: Name of the bound route or A/B template, or `null` if it was deleted (the link then uses its original destination).
        routeTemplateId:
          type:
          - integer
          - 'null'
          description: 'Numeric ID of the bound route template (`null` for A/B bindings). Deprecated: use `templateName`.'
          deprecated: true
        abTemplateId:
          type:
          - integer
          - 'null'
          description: 'Numeric ID of the bound A/B template (`null` for Device bindings). Deprecated: use `templateName`.'
          deprecated: true
        createdDate:
          type: string
          format: date-time
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
    BindingCreated:
      type: object
      required:
      - shortCode
      - routingType
      - templateName
      - endpoints
      properties:
        shortCode:
          type: string
        routingType:
          $ref: '#/components/schemas/RoutingType'
        templateName:
          type: string
        endpoints:
          type: array
          items:
            $ref: '#/components/schemas/Endpoint'
  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.
    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'
    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
  parameters:
    ShortCode:
      name: code
      in: path
      required: true
      description: Short code of one of your links (the part after `https://gajo.io/` or `https://gajo.io/c/`).
      schema:
        type: string
        pattern: ^[A-Za-z0-9-]{3,50}$
      example: Xk4mPq
  headers:
    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
    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
  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