JustIdea Content API

openapi: 3.2.0
info:
  title: Justidea Agency Content API
  version: 1.0.0
  contact:
    name: JustIdea Agency
    email: contact@justidea.agency
    url: https://justidea.agency/en/contact/
  license:
    name: Proprietary. Public content of justidea.agency, free to read and quote with attribution.
  description: 'Operations tagged content across 2 of this provider''s published API definitions: justidea-agency-openapi.json, justidea-agency-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://justidea.agency
  description: justidea.agency
security:
- {}
- agentOAuth:
  - site:read
tags:
- name: Content
  description: Search and read public pages.
paths:
  /api/v1/search:
    get:
      operationId: searchSite
      tags:
      - Content
      summary: Search the website
      description: Search over the public pages of justidea.agency (services, pricing, case studies, company pages, city pages and blog posts in Polish and English). 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'
    servers:
    - url: https://justidea.agency
      description: justidea.agency
  /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'
    servers:
    - url: https://justidea.agency
      description: justidea.agency
  /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). Accepts a full URL, a path or the .md address of the 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'
    servers:
    - url: https://justidea.agency
      description: justidea.agency
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 of the page.
        type:
          type: string
          enum:
          - services_index
          - service_area
          - service
          - city_page
          - pricing
          - case_studies
          - event
          - blog
          - company
        lang:
          type: string
          enum:
          - pl
          - en
        matchingSections:
          type: array
          items:
            type: string
          description: 'Search only: section headings that matched the query.'
    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
        title:
          type: string
        lang:
          type: string
          enum:
          - pl
          - en
        type:
          type: string
          enum:
          - services_index
          - service_area
          - service
          - city_page
          - pricing
          - case_studies
          - event
          - blog
          - company
        markdown:
          type: string
          description: Page content as Markdown.
        truncated:
          type: boolean
          description: True when the page was longer than 80000 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:
        - services_index
        - service_area
        - service
        - city_page
        - pricing
        - case_studies
        - event
        - blog
        - company
    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 Polish or English, e.g. "sklep prestashop cena", "SEO audit", "kampanie Google Ads".
      schema:
        type: string
        minLength: 1
        maxLength: 200
    Url:
      name: url
      in: query
      required: true
      description: Page URL on justidea.agency, a path starting with "/" or the .md address, e.g. "/pl/uslugi/sklepy-internetowe/".
      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
    SearchLimit:
      name: limit
      in: query
      required: false
      description: Maximum number of results.
      schema:
        type: integer
        minimum: 1
        maximum: 25
        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://justidea.agency/.well-known/oauth-protected-resource", scope="site:read", error="invalid_token", error_description="The access token is invalid or expired"
          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://justidea.agency/auth.md.
      flows:
        authorizationCode:
          authorizationUrl: https://justidea.agency/oauth/authorize/
          tokenUrl: https://justidea.agency/oauth/token/
          refreshUrl: https://justidea.agency/oauth/token/
          scopes:
            site:read: Read public content of justidea.agency (REST API and MCP server).
externalDocs:
  description: 'Reference in Markdown: error types, limits, examples.'
  url: https://justidea.agency/api.md
x-refined-from:
- justidea-agency-openapi.json
- justidea-agency-openapi.yml