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.
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.
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-bindings-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 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