Gajo Route Templates API

Pro. Reusable, abstract device-routing templates (device slots only, no URLs).

GitHub OpenAPI

Operations 6

GET /route-templates List route templates #
POST /route-templates Create a route template #
GET /route-templates/{name} Get a route template #
PUT /route-templates/{name} Replace a route template's rules #
PATCH /route-templates/{name} Rename a route template #
DELETE /route-templates/{name} Delete a route 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-route-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-route-templates-api-openapi.yml Raw ↑
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