Iterant Public: Linking API

The Public: Linking API from Iterant — 1 operation(s) for public: linking.

GitHub OpenAPI

Operations 1

GET /api/v1/public/brands/{brandSlug}/linking/advisory/ Get internal-linking recommendations #

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/iterant-ai:iterant-ai-public-linking-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

iterant-ai-public-linking-api-openapi.yml Raw ↑
openapi: 3.2.0
info:
  title: 'Iterant Public Public: Linking API'
  version: 1.0.0
  description: 'The Iterant public API: read a brand''s pages, page opportunities, reports and AI visibility, and start Iterant''s agent on a page. Guides: https://iterant.ai/docs/developers/rest-api


    **Authentication.** Send `Authorization: Bearer itr_...`, an API key an organization admin mints at Settings > Developers.


    **Rate limits.** 600 requests per minute per key, and 30 task starts per minute. Responses carry the IETF `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` and `RateLimit-Policy` fields. A `429` carries `Retry-After` in seconds. Requests without a valid key are limited to 60 per minute per client IP.


    **Idempotency.** `POST .../tasks/` takes an `Idempotency-Key` header. For 24 hours, a retry with the same key and body returns the first task instead of starting a second.


    **Versioning and deprecation.** The version is in the path: `/api/v1/`. Breaking changes ship under a new version. A deprecated version keeps working for at least 6 months after the announcement, and its responses carry `Deprecation` and `Sunset` headers (RFC 9745, RFC 8594). Nothing is deprecated today. Policy: https://iterant.ai/docs/developers/rest-api#versioning-and-deprecation'
servers:
- url: https://api.iterant.ai
  description: Production server
tags:
- name: 'Public: Linking'
paths:
  /api/v1/public/brands/{brandSlug}/linking/advisory/:
    get:
      operationId: publicLinkingAdvisory
      description: 'Internal links worth adding *to* a page: which existing pages should link to it, the suggested anchor text, and the passage the link would sit in.


        `relevance` is 0-1; below about 0.6 a placement is usually not worth making. An empty `links` array is a real answer: nothing on the site is a good enough source yet.


        These are advisory. This endpoint never edits a page, and Iterant does not place these links itself: the source pages are the customer''s own, hand-built ones.


        `responseFormat=detailed` adds the anchor variants and the passage excerpt.'
      summary: Get internal-linking recommendations
      parameters:
      - in: path
        name: brandSlug
        schema:
          type: string
        required: true
      - in: query
        name: responseFormat
        schema:
          type: string
          enum:
          - concise
          - detailed
          default: concise
        description: 'How much to return. `concise` (the default) omits long-form text: briefs, outlines, evidence, passage excerpts, per-dimension breakdowns. `detailed` includes it and costs several times the tokens.'
      - in: query
        name: urlPath
        schema:
          type: string
        description: Page route as returned by the pages list, e.g. "/pricing". Always starts with "/".
      tags:
      - 'Public: Linking'
      security:
      - tenantApiKeyAuth: []
      responses:
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicLinkingAdvisoryErrorResponse400'
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse401'
              examples:
                AuthenticationFailed:
                  value:
                    type: client_error
                    errors:
                    - code: authentication_failed
                      detail: Incorrect authentication credentials.
                      attr: null
                NotAuthenticated:
                  value:
                    type: client_error
                    errors:
                    - code: not_authenticated
                      detail: Authentication credentials were not provided.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse404'
              examples:
                NotFound:
                  value:
                    type: client_error
                    errors:
                    - code: not_found
                      detail: Not found.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '405':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse405'
              examples:
                MethodNotAllowed:
                  value:
                    type: client_error
                    errors:
                    - code: method_not_allowed
                      detail: Method "get" not allowed.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '406':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse406'
              examples:
                NotAcceptable:
                  value:
                    type: client_error
                    errors:
                    - code: not_acceptable
                      detail: Could not satisfy the request Accept header.
                      attr: null
          description: ''
        '415':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse415'
              examples:
                UnsupportedMediaType:
                  value:
                    type: client_error
                    errors:
                    - code: unsupported_media_type
                      detail: Unsupported media type "application/json" in request.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse429'
              examples:
                Throttled:
                  value:
                    type: client_error
                    errors:
                    - code: throttled
                      detail: Request was throttled.
                      attr: null
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
        '500':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse500'
              examples:
                APIException:
                  value:
                    type: server_error
                    errors:
                    - code: error
                      detail: A server error occurred.
                      attr: null
          description: ''
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicLinkingRecommendations'
              examples:
                TwoRecommendedInboundLinks:
                  value:
                    brandSlug: orbital-labs
                    urlPath: /compare/orbital-vs-datadog
                    stale: false
                    links:
                    - sourceUrl: https://orbital-labs.com/docs/tracing
                      anchorText: compare Orbital and Datadog
                      relevance: 0.81
                    note: ''
                  summary: Two recommended inbound links
          description: ''
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            RateLimit-Remaining:
              $ref: '#/components/headers/RateLimit-Remaining'
            RateLimit-Reset:
              $ref: '#/components/headers/RateLimit-Reset'
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
components:
  schemas:
    ParseErrorCodeEnum:
      enum:
      - parse_error
      type: string
      description: '* `parse_error` - Parse Error'
    PublicAdvisoryLink:
      type: object
      properties:
        sourceUrl:
          type: string
        anchorText:
          type: string
        anchorVariants:
          type: array
          items:
            type: string
        relevance:
          type: number
          format: double
        passageExcerpt:
          type: string
      required:
      - anchorText
      - relevance
      - sourceUrl
    ErrorCode404Enum:
      enum:
      - not_found
      type: string
      description: '* `not_found` - Not Found'
    Error405:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode405Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    PublicLinkingRecommendations:
      type: object
      properties:
        brandSlug:
          type: string
        urlPath:
          type: string
        stale:
          type: boolean
          description: True when a source page was re-crawled after its recommendation was computed, so the passage may have moved. The recommendations are still returned.
        links:
          type: array
          items:
            $ref: '#/components/schemas/PublicAdvisoryLink'
        note:
          type: string
      required:
      - brandSlug
      - links
      - note
      - stale
      - urlPath
    Error406:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode406Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ParseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ParseErrorCodeEnum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ErrorCode415Enum:
      enum:
      - unsupported_media_type
      type: string
      description: '* `unsupported_media_type` - Unsupported Media Type'
    ParseErrorResponse:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ParseError'
      required:
      - errors
      - type
    ErrorResponse405:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error405'
      required:
      - errors
      - type
    ErrorResponse429:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error429'
      required:
      - errors
      - type
    Error500:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode500Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    Error415:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode415Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ServerErrorEnum:
      enum:
      - server_error
      type: string
      description: '* `server_error` - Server Error'
    ErrorResponse404:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error404'
      required:
      - errors
      - type
    ErrorCode406Enum:
      enum:
      - not_acceptable
      type: string
      description: '* `not_acceptable` - Not Acceptable'
    ErrorCode405Enum:
      enum:
      - method_not_allowed
      type: string
      description: '* `method_not_allowed` - Method Not Allowed'
    PublicLinkingAdvisoryErrorResponse400:
      oneOf:
      - $ref: '#/components/schemas/ParseErrorResponse'
      discriminator:
        propertyName: type
        mapping:
          client_error: '#/components/schemas/ParseErrorResponse'
    ErrorResponse415:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error415'
      required:
      - errors
      - type
    Error404:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode404Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ErrorResponse401:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error401'
      required:
      - errors
      - type
    ErrorResponse406:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ClientErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error406'
      required:
      - errors
      - type
    ErrorResponse500:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/ServerErrorEnum'
        errors:
          type: array
          items:
            $ref: '#/components/schemas/Error500'
      required:
      - errors
      - type
    Error429:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode429Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
    ErrorCode401Enum:
      enum:
      - authentication_failed
      - not_authenticated
      type: string
      description: '* `authentication_failed` - Authentication Failed

        * `not_authenticated` - Not Authenticated'
    ErrorCode429Enum:
      enum:
      - throttled
      type: string
      description: '* `throttled` - Throttled'
    ErrorCode500Enum:
      enum:
      - error
      type: string
      description: '* `error` - Error'
    ClientErrorEnum:
      enum:
      - client_error
      type: string
      description: '* `client_error` - Client Error'
    Error401:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ErrorCode401Enum'
        detail:
          type: string
        attr:
          type:
          - string
          - 'null'
      required:
      - attr
      - code
      - detail
  headers:
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    RateLimit-Remaining:
      description: Requests left in the current window.
      schema:
        type: integer
    RateLimit-Reset:
      description: Seconds until the budget has room again.
      schema:
        type: integer
    RateLimit-Limit:
      description: Requests allowed per window, for the tightest budget this request drew on.
      schema:
        type: integer
    RateLimit-Policy:
      description: The budget as `<limit>;w=<window seconds>`, e.g. `600;w=60`.
      schema:
        type: string
  securitySchemes:
    tenantApiKeyAuth:
      type: http
      scheme: bearer