JustIdea Agents API

openapi: 3.2.0
info:
  title: Justidea Agency Agents 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 agents 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: Agents
  description: Agent identity and batch reads.
paths:
  /api/v1/identity:
    get:
      operationId: getAgentIdentity
      tags:
      - Agents
      summary: Identify the calling agent
      description: Who the bearer token belongs to and which rate limit applies. Requires a token; without one returns 401 with WWW-Authenticate pointing at the protected resource metadata.
      security:
      - agentOAuth:
        - site:read
      responses:
        '200':
          description: The agent behind the token.
          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/AgentIdentity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://justidea.agency
      description: justidea.agency
  /agent/identity:
    get:
      operationId: getAgentIdentityWellKnown
      tags:
      - Agents
      summary: Identify the calling agent (agent-auth address)
      description: Same as getAgentIdentity, at the address agent-auth clients look for.
      security:
      - agentOAuth:
        - site:read
      responses:
        '200':
          description: The agent behind the token.
          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/AgentIdentity'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://justidea.agency
      description: justidea.agency
  /api/v1/batch:
    post:
      operationId: batchRead
      tags:
      - Agents
      summary: Run several reads in one request
      description: Runs 1 to 10 GET operations on /api/v1 endpoints (except batch, identity and the API documents) and returns each status and body in order. Read-only and free of side effects, so it is always safe to retry; counts as one request against the rate limit. An optional Idempotency-Key is accepted and echoed back.
      parameters:
      - $ref: '#/components/parameters/IdempotencyKey'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchRequest'
      responses:
        '200':
          description: Results in request order.
          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'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/InvalidToken'
        '413':
          $ref: '#/components/responses/PayloadTooLarge'
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalError'
    servers:
    - url: https://justidea.agency
      description: justidea.agency
components:
  parameters:
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: Optional client-chosen key (1 to 255 visible ASCII characters), echoed back. The batch has no side effects, so a retry with or without the key is always safe.
      schema:
        type: string
        minLength: 1
        maxLength: 255
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per 60-second window.
      schema:
        type: integer
    Idempotency-Key:
      description: The Idempotency-Key sent with the request, echoed back.
      schema:
        type: string
    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
    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
  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'
    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'
    InternalError:
      description: Unexpected error (code internal-error). Retry later.
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    Unauthorized:
      description: A bearer token is required (code unauthorized).
      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"
          schema:
            type: string
    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
    UnsupportedMediaType:
      description: The request body is not JSON (code unsupported-media-type).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
    PayloadTooLarge:
      description: The request body is too large (code payload-too-large).
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  schemas:
    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.
    BatchRequest:
      type: object
      required:
      - requests
      properties:
        requests:
          type: array
          minItems: 1
          maxItems: 10
          items:
            type: object
            required:
            - path
            properties:
              id:
                type:
                - string
                - integer
                description: Echoed back in the result; defaults to the position.
              method:
                type: string
                enum:
                - GET
                default: GET
              path:
                type: string
                description: Path with query string, e.g. "/api/v1/search?q=prestashop".
                pattern: ^/api/v1
    BatchResponse:
      type: object
      required:
      - responses
      properties:
        responses:
          type: array
          items:
            type: object
            required:
            - id
            - status
            - body
            properties:
              id:
                type:
                - string
                - integer
              status:
                type: integer
              body:
                description: 'The body the same GET would return: its success schema or Problem.'
                type: object
    AgentIdentity:
      type: object
      required:
      - authenticated
      - sub
      - scope
      - resource
      - rateLimit
      properties:
        authenticated:
          type: boolean
          const: true
        sub:
          type: string
          description: Agent identifier from the token.
        scope:
          type: string
        resource:
          type: string
          format: uri
        rateLimit:
          type: object
          required:
          - policy
          - limit
          - windowSeconds
          properties:
            policy:
              type: string
            limit:
              type: integer
            windowSeconds:
              type: integer
  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