JustAutomate Content API

openapi: 3.2.0
info:
  title: JustAutomate public Content API
  version: 1.0.0
  summary: 'Read-only API for the public website of JustAutomate: search and read pages, the process workshop price and contact options.'
  description: 'JustAutomate (justautomate.ai) is a Polish B2B agency that designs and implements AI agents, process automation and system integrations for companies in Poland, Germany, Austria, Switzerland and English-speaking markets.


    This API is **read-only** and exposes only what is public on the website. It never submits forms, books meetings or sends messages: to get in touch, give the user the contact link or e-mail address from `GET /api/v1/contact`. The same data is available over MCP at https://justautomate.ai/mcp.


    **Authentication.** None required. An optional OAuth 2.1 bearer token (scope `mcp:read`, see https://justautomate.ai/auth.md) identifies the agent and raises the rate limit. An invalid or expired token gets `401` with a `WWW-Authenticate` header pointing at https://justautomate.ai/.well-known/oauth-protected-resource; `GET /api/v1/identity` always needs a token.


    **Rate limits.** 120 requests per 60 seconds per IP address, 600 per agent with a token. Every response carries `RateLimit-Policy` (IETF RateLimit header fields) and `X-RateLimit-Limit`. A `429` carries `Retry-After` (seconds) and `RateLimit` with the remaining quota (0). A batch counts as one request.


    **Errors.** Every 4xx and 5xx response is `application/problem+json` (RFC 9457) with `type`, `title`, `status`, `detail`, `instance` and a machine-readable `code`. Each `type` URI points at its section of https://justautomate.ai/api.md.


    **Pagination.** `GET /api/v1/pages` is cursor-based: pass `next_cursor` from the response as `cursor` until it is `null`. The next page is also in the `Link: ; rel="next"` header. Cursors are opaque.


    **Versioning and deprecation.** The major version is in the path (`/api/v1`). Within v1 changes are additive only: new endpoints, new optional parameters, new response fields. Clients must ignore unknown fields. A breaking change ships as `/api/v2`; v1 then keeps working and its responses carry a `Deprecation` header (RFC 9745) from the day the decision is made and a `Sunset` header (RFC 8594) with the removal date, at least 90 days later. `info.version` follows SemVer.


    **Batch and retries.** `POST /api/v1/batch` runs up to 10 GET operations in one request. All operations are read-only and have no side effects, so every request, including a batch, is safe to retry. An optional `Idempotency-Key` header on the batch is accepted and echoed back.


    All prices are net, excluding VAT. The only public price is the process workshop; implementation is quoted after it.'
  termsOfService: https://justautomate.ai/regulamin/
  contact:
    name: JustAutomate
    email: contact@justautomate.ai
    url: https://justautomate.ai/en/contact/
  license:
    name: Proprietary. Public content of justautomate.ai, free to read and quote with attribution.
    url: https://justautomate.ai/regulamin/
servers:
- url: https://justautomate.ai
  description: Production
security:
- {}
- agentOAuth:
  - mcp:read
tags:
- name: Content
  description: Search and read public pages.
paths:
  /api/v1/search:
    get:
      operationId: searchSite
      tags:
      - Content
      summary: Search the website
      description: Full-text search over the public pages of justautomate.ai (services, products, industry offers, guides and blog posts in Polish, English and German, plus local pages for selected German-speaking cities). Returns titles, descriptions and URLs ranked by relevance; read a result with getPage.
      parameters:
      - $ref: '#/components/parameters/Query'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/PageType'
      - $ref: '#/components/parameters/SearchLimit'
      responses:
        '200':
          description: Search results.
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResults'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidToken'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v1/pages:
    get:
      operationId: listPages
      tags:
      - Content
      summary: List pages
      description: Public pages, optionally filtered by kind and language, with cursor pagination.
      parameters:
      - $ref: '#/components/parameters/PageType'
      - $ref: '#/components/parameters/Lang'
      - $ref: '#/components/parameters/PageLimit'
      - $ref: '#/components/parameters/Cursor'
      responses:
        '200':
          description: One page of results.
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageList'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidToken'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
  /api/v1/page:
    get:
      operationId: getPage
      tags:
      - Content
      summary: Read a page as Markdown
      description: The content of one public page as clean Markdown (no navigation, scripts or forms), with title, description and canonical URL in the front matter. Accepts a full URL or a path. Old addresses are followed to their current page.
      parameters:
      - $ref: '#/components/parameters/Url'
      responses:
        '200':
          description: Page content.
          headers:
            RateLimit-Policy:
              $ref: '#/components/headers/RateLimit-Policy'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            Deprecation:
              $ref: '#/components/headers/Deprecation'
            Sunset:
              $ref: '#/components/headers/Sunset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageContent'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidToken'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/Unavailable'
components:
  schemas:
    PageSummary:
      type: object
      required:
      - title
      - url
      - markdownUrl
      - type
      - lang
      properties:
        title:
          type: string
        url:
          type: string
          format: uri
          description: Canonical URL of the page.
        markdownUrl:
          type: string
          format: uri
          description: The same page as Markdown.
        description:
          type: string
          description: Meta description. City pages have none.
        type:
          type: string
          enum:
          - home
          - section
          - offer
          - guide
          - blog
          - about
          - contact
          - city
          - legal
          - other
        lang:
          type: string
          enum:
          - pl
          - en
          - de
    PageList:
      type: object
      required:
      - data
      - total
      - limit
      - next_cursor
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PageSummary'
        total:
          type: integer
          description: Number of pages matching the filters.
        limit:
          type: integer
        next_cursor:
          type:
          - string
          - 'null'
          description: Pass as cursor to get the next page; null on the last page.
    SearchResults:
      type: object
      required:
      - query
      - data
      properties:
        query:
          type: string
        data:
          type: array
          items:
            $ref: '#/components/schemas/PageSummary'
        note:
          type: string
    Problem:
      type: object
      description: Error in RFC 9457 format.
      required:
      - type
      - title
      - status
      - code
      properties:
        type:
          type: string
          format: uri
          description: Link to the description of this error in /api.md.
        title:
          type: string
          description: Short summary of the error type.
        status:
          type: integer
          description: HTTP status code.
        detail:
          type: string
          description: What went wrong in this request and how to fix it.
        instance:
          type: string
          description: Path of the request that failed.
        code:
          type: string
          enum:
          - invalid-parameter
          - invalid-body
          - unsupported-media-type
          - payload-too-large
          - unauthorized
          - invalid-token
          - not-found
          - method-not-allowed
          - rate-limited
          - unavailable
          - internal-error
          description: Machine-readable error code.
    PageContent:
      type: object
      required:
      - url
      - markdownUrl
      - markdown
      - truncated
      properties:
        url:
          type: string
          format: uri
        markdownUrl:
          type: string
          format: uri
        markdown:
          type: string
          description: Page content as Markdown with YAML front matter (title, description, url, lang).
        truncated:
          type: boolean
          description: True when the page was longer than 120000 characters and was cut.
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per 60-second window.
      schema:
        type: integer
    Sunset:
      description: 'Present only once a removal date is set (RFC 8594): the HTTP-date after which the endpoint stops answering, at least 90 days after Deprecation first appeared.'
      schema:
        type: string
    Link:
      description: 'RFC 8288 link to the next page: <url>; rel="next". Absent on the last page.'
      schema:
        type: string
    RateLimit:
      description: Remaining quota (IETF RateLimit header fields). Sent with 429, where it is 0.
      schema:
        type: string
    X-RateLimit-Remaining:
      description: Requests left in the window. Sent with 429, where it is 0.
      schema:
        type: integer
    Retry-After:
      description: Seconds to wait before retrying.
      schema:
        type: integer
    Deprecation:
      description: 'Present only once this endpoint or API version is deprecated: the date the deprecation took effect (RFC 9745). Absent on every endpoint today.'
      schema:
        type: string
    RateLimit-Policy:
      description: 'Quota policy (IETF RateLimit header fields): "ip";q=120;w=60 without a token, "agent";q=600;w=60 with one.'
      schema:
        type: string
  parameters:
    PageLimit:
      name: limit
      in: query
      required: false
      description: Maximum number of pages in one response.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    PageType:
      name: type
      in: query
      required: false
      description: Only pages of this kind.
      schema:
        type: string
        enum:
        - home
        - section
        - offer
        - guide
        - blog
        - about
        - contact
        - city
        - legal
        - other
    Cursor:
      name: cursor
      in: query
      required: false
      description: 'Opaque cursor: next_cursor from the previous response. Omit for the first page.'
      schema:
        type: string
        maxLength: 64
    Query:
      name: q
      in: query
      required: true
      description: What to look for, in any of the site languages, e.g. "process workshop price", "KI-Agentur Wien", "automatyzacja faktur".
      schema:
        type: string
        minLength: 1
        maxLength: 200
    Url:
      name: url
      in: query
      required: true
      description: Page URL on justautomate.ai or a path starting with "/", e.g. "/en/services/process-workshop/".
      schema:
        type: string
        minLength: 1
        maxLength: 500
    Lang:
      name: lang
      in: query
      required: false
      description: Only pages in this language.
      schema:
        type: string
        enum:
        - pl
        - en
        - de
    SearchLimit:
      name: limit
      in: query
      required: false
      description: Maximum number of results.
      schema:
        type: integer
        minimum: 1
        maximum: 20
        default: 8
  responses:
    BadRequest:
      description: A parameter or the request body is invalid (code invalid-parameter or invalid-body).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unavailable:
      description: Site data is temporarily unavailable (code unavailable). Wait Retry-After seconds.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
    TooManyRequests:
      description: Rate limit exceeded (code rate-limited). Wait Retry-After seconds.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        RateLimit:
          $ref: '#/components/headers/RateLimit'
        RateLimit-Policy:
          $ref: '#/components/headers/RateLimit-Policy'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
    NotFound:
      description: No such public page or endpoint (code not-found).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InternalError:
      description: Unexpected error (code internal-error). Retry later.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    InvalidToken:
      description: The bearer token is invalid or expired (code invalid-token). Call without a token or get a new one.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
      headers:
        WWW-Authenticate:
          description: Bearer resource_metadata="https://justautomate.ai/.well-known/oauth-protected-resource", scope="mcp:read", error="invalid_token"
          schema:
            type: string
  securitySchemes:
    agentOAuth:
      type: oauth2
      description: Optional. Identifies the agent and raises the rate limit to 600 requests per minute. Dynamic client registration and anonymous agent registration are described at https://justautomate.ai/auth.md.
      flows:
        authorizationCode:
          authorizationUrl: https://justautomate.ai/oauth/authorize/
          tokenUrl: https://justautomate.ai/oauth/token/
          refreshUrl: https://justautomate.ai/oauth/token/
          scopes:
            mcp:read: Read public content of justautomate.ai (REST API and MCP server).
externalDocs:
  description: 'Developer portal: quickstart, self-serve token, testing. Reference in Markdown: /api.md'
  url: https://justautomate.ai/developers/