Gajo Route Templates API
Pro. Reusable, abstract device-routing templates (device slots only, no URLs).
Pro. Reusable, abstract device-routing templates (device slots 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-route-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 Route 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: Route Templates
description: Pro. Reusable, abstract device-routing templates (device slots only, no URLs).
paths:
/route-templates:
get:
operationId: listRouteTemplates
tags:
- Route Templates
summary: List route templates
description: '**Requires a Pro plan.** Returns your active route templates. Route templates are abstract: they list device slots but contain no URLs. Concrete destinations are set per link with `POST /urls/{code}/binding`.'
x-gajo-plan: Pro
responses:
'200':
description: Your route 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/RouteTemplateListResult'
example:
success: true
message: null
data:
- name: app-store-router
description: Phones to the app, everyone else to the website
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: null
rules:
- deviceType: IOS
priority: 0
- deviceType: Android
priority: 1
- deviceType: Default
priority: 2
'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 route templates
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
post:
operationId: createRouteTemplate
tags:
- Route Templates
summary: Create a route template
description: '**Requires a Pro plan.** Creates a reusable device-routing template from a list of device slots (`Android`, `IOS`, `Mobile`, `Tablet`, `Desktop`, `Default`), each at most once. At redirect time OS-specific slots win over device classes, and `Default` catches everything else. Route templates are abstract: they list device slots but contain 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/RouteTemplateRequest'
example:
name: app-store-router
description: Phones to the app, everyone else to the website
rules:
- deviceType: IOS
- deviceType: Android
- deviceType: Default
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/RouteTemplateResult'
example:
success: true
message: Route template created
data:
name: app-store-router
description: Phones to the app, everyone else to the website
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: null
rules:
- deviceType: IOS
priority: 0
- deviceType: Android
priority: 1
- deviceType: Default
priority: 2
'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
noRules:
summary: Empty rules array
value:
success: false
message: At least one device rule is required
data: null
duplicate:
summary: Repeated deviceType
value:
success: false
message: Duplicate device types are not allowed
data: null
badDeviceType:
summary: Unknown deviceType
value:
success: false
message: 'Invalid device type: Phone. Must be one of: Android, IOS, Mobile, Tablet, Desktop, Default'
data: null
exists:
summary: Name already used
value:
success: false
message: A route template named 'app-store-router' 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 route templates
'429':
$ref: '#/components/responses/RateLimited'
'500':
$ref: '#/components/responses/ServerError'
/route-templates/{name}:
parameters:
- $ref: '#/components/parameters/TemplateName'
get:
operationId: getRouteTemplate
tags:
- Route Templates
summary: Get a route template
description: '**Requires a Pro plan.** Returns one route 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/RouteTemplateResult'
example:
success: true
message: null
data:
name: app-store-router
description: Phones to the app, everyone else to the website
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: null
rules:
- deviceType: IOS
priority: 0
- deviceType: Android
priority: 1
- deviceType: Default
priority: 2
'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 route templates
'404':
description: No route template with this name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: Route 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: updateRouteTemplate
tags:
- Route Templates
summary: Replace a route template's rules
description: '**Requires a Pro plan.** Replaces the template''s description and full list of device slots. 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 change immediately.'
x-gajo-plan: Pro
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/RouteTemplateRequest'
example:
name: app-store-router
description: Phones to the app, everyone else to the website
rules:
- deviceType: IOS
- deviceType: Android
- deviceType: Tablet
- deviceType: Default
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/RouteTemplateResult'
example:
success: true
message: Route template updated
data:
name: app-store-router
description: Phones to the app, everyone else to the website
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: '2026-10-08T09:15:00.250Z'
rules:
- deviceType: IOS
priority: 0
- deviceType: Android
priority: 1
- deviceType: Tablet
priority: 2
- deviceType: Default
priority: 3
'400':
description: Invalid request. `message` explains what to fix.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
examples:
noRules:
summary: Empty rules array
value:
success: false
message: At least one device rule is required
data: null
duplicate:
summary: Repeated deviceType
value:
success: false
message: Duplicate device types are not allowed
data: null
badDeviceType:
summary: Unknown deviceType
value:
success: false
message: 'Invalid device type: Phone. Must be one of: Android, IOS, Mobile, Tablet, Desktop, Default'
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 route templates
'404':
description: No route template with this name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: Route template 'app-store-router' 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: renameRouteTemplate
tags:
- Route Templates
summary: Rename a route 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: app-router-v2
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/RouteTemplateResult'
example:
success: true
message: Route template renamed
data:
name: app-router-v2
description: Phones to the app, everyone else to the website
active: true
createdDate: '2026-10-07T14:03:11.482Z'
updatedDate: '2026-10-08T09:15:00.250Z'
rules:
- deviceType: IOS
priority: 0
- deviceType: Android
priority: 1
- deviceType: Default
priority: 2
'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: A route template named 'app-router-v2' 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 route templates
'404':
description: No route template with this name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: Route template 'app-store-router' 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: deleteRouteTemplate
tags:
- Route Templates
summary: Delete a route template
description: '**Requires a Pro plan.** Deletes the template. Links bound to it stop routing through it 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: Route 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 route templates
'404':
description: No route template with this name.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResult'
example:
success: false
message: Route template 'app-store-router' 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'
RouteTemplateRequest:
type: object
required:
- name
- rules
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.
rules:
type: array
minItems: 1
maxItems: 6
description: Device slots in this template; each `deviceType` may appear once. Include `Default` to catch unmatched devices.
items:
type: object
required:
- deviceType
properties:
deviceType:
$ref: '#/components/schemas/DeviceSlot'
RouteTemplate:
type: object
description: 'An abstract device-routing template: device slots only, no URLs.'
required:
- name
- description
- active
- createdDate
- updatedDate
- rules
properties:
name:
type: string
description:
type:
- string
- 'null'
active:
type: boolean
createdDate:
type: string
format: date-time
updatedDate:
type:
- string
- 'null'
format: date-time
rules:
type: array
items:
type: object
required:
- deviceType
- priority
properties:
deviceType:
$ref: '#/components/schemas/DeviceSlot'
priority:
type: integer
minimum: 0
description: Position in the template (0-based, request order).
RouteTemplateResult:
description: Envelope with one route template.
allOf:
- $ref: '#/components/schemas/ApiResult'
- type: object
required:
- data
properties:
success:
const: true
data:
$ref: '#/components/schemas/RouteTemplate'
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.
RouteTemplateListResult:
description: Envelope with route templates.
allOf:
- $ref: '#/components/schemas/ApiResult'
- type: object
required:
- data
properties:
success:
const: true
data:
type: array
items:
$ref: '#/components/schemas/RouteTemplate'
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.
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