Hjarni Me API

openapi: 3.2.0
info:
  title: Hjarni REST Me API
  version: 1.0.0
  description: Hjarni is a Markdown knowledge base that AI assistants and people share; this API reads and writes the same notes, folders (called containers) and tags that its MCP server exposes. Requests go to https://hjarni.com/api/v1 with a bearer token in the Authorization header, send and receive JSON, and list endpoints page with `page` and `per_page` and report totals in the `X-Total-Count`, `X-Page` and `X-Per-Page` headers. Requests are limited to 100 a minute per account across all of its tokens, and going over answers 429 with a `Retry-After` header.
  termsOfService: https://hjarni.com/terms
  contact:
    name: Hjarni
    email: evert@hjarni.com
    url: https://hjarni.com/docs/api
servers:
- url: https://hjarni.com/api/v1
security:
- bearerAuth: []
tags:
- name: Me
  description: The account and the token making the request.
paths:
  /me:
    get:
      operationId: getMe
      summary: Get the account and token
      description: Returns the account behind the token (`user`, with `plan`) and a `token` block describing the token itself. A full-access token also gets `onboarding`, `teams`, `limits` and `suggestions`; an agent token gets only `user` and `token`, and its `token` block adds the `grants` it holds, the `instructions` written for that agent, and `follows_brain_instructions`. Call it first to learn what the token can reach.
      tags:
      - Me
      responses:
        '200':
          description: The account and the token.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Me'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
components:
  schemas:
    MeUser:
      type: object
      required:
      - id
      - first_name
      - email_address
      - plan
      - email
      properties:
        id:
          type: integer
        first_name:
          type:
          - string
          - 'null'
        email_address:
          type: string
          format: email
        plan:
          type: string
          description: The stored plan name, "free" or "pro".
        email:
          type: string
          format: email
          deprecated: true
          description: Same as email_address, kept for older clients.
    Limits:
      type: object
      description: Personal allowances; a null limit means unlimited.
      required:
      - notes_used
      - notes_limit
      - file_storage_bytes_used
      - file_storage_bytes_limit
      - files_used
      - files_limit
      properties:
        notes_used:
          type: integer
        notes_limit:
          type:
          - integer
          - 'null'
        file_storage_bytes_used:
          type: integer
        file_storage_bytes_limit:
          type:
          - integer
          - 'null'
        files_used:
          type: integer
        files_limit:
          type:
          - integer
          - 'null'
    Me:
      type: object
      description: '`onboarding`, `teams`, `limits` and `suggestions` are present for a full-access token and absent for an agent token.'
      required:
      - user
      - token
      properties:
        user:
          $ref: '#/components/schemas/MeUser'
        token:
          $ref: '#/components/schemas/MeToken'
        onboarding:
          $ref: '#/components/schemas/Onboarding'
        teams:
          type: array
          description: Teams the person belongs to, by name.
          items:
            $ref: '#/components/schemas/TeamMembershipInfo'
        limits:
          $ref: '#/components/schemas/Limits'
        suggestions:
          type: object
          required:
          - create_team
          properties:
            create_team:
              type: boolean
              description: True when the person is a good fit to be offered a team.
    ContainerRef:
      type: object
      required:
      - id
      - name
      properties:
        id:
          type: integer
        name:
          type: string
    Error:
      type: object
      description: 'Every error response carries `error`. The generic statuses also carry `code`, `message` and `docs_url`: 401, a 403 for an agent token outside its grants, and any status answered for a raised error or an unknown endpoint (400, 404, 5xx). Plan-limit 403s carry `upgrade_url` instead. Some endpoint-specific errors carry `error` alone.'
      required:
      - error
      properties:
        status:
          type: integer
          description: The HTTP status again. Present on errors raised inside the app and on unknown endpoints (400, 404, 5xx), not on 401 or the 403s.
        error:
          type: string
          description: Human-readable message.
        errors:
          type: array
          items:
            type: string
          description: 'Only on a validation failure raised inside the app (422): one message per problem.'
        code:
          type: string
          description: 'Machine-readable code: `unauthorized` (401), `out_of_scope` (403, agent token), or for a raised error or unknown endpoint the snake_case name of the HTTP status, such as `bad_request`, `not_found`, `unprocessable_content` or `internal_server_error`.'
          examples:
          - unauthorized
          - out_of_scope
          - not_found
          - internal_server_error
        message:
          type: string
          description: What to do about it.
        docs_url:
          type: string
          format: uri
          description: The documentation page that explains this error.
        upgrade_url:
          type: string
          format: uri-reference
          description: Only on plan-limit 403s. A path on hjarni.com (relative, so prefix https://hjarni.com) to the checkout that lifts the limit.
        team_url:
          type: string
          format: uri-reference
          description: Only on the personal note-limit 403 from POST /notes. A relative path to creating a team, the other way past the personal limit.
    Onboarding:
      type: object
      required:
      - completed
      - completed_at
      - signals
      - missing_steps
      properties:
        completed:
          type: boolean
        completed_at:
          type:
          - string
          - 'null'
          format: date-time
        signals:
          type: object
          required:
          - connected_mcp
          - has_real_notes
          - has_custom_instructions
          - team_brain_available
          properties:
            connected_mcp:
              type: boolean
            has_real_notes:
              type: boolean
            has_custom_instructions:
              type: boolean
            team_brain_available:
              type: boolean
        missing_steps:
          type: array
          items:
            type: string
            enum:
            - connect_mcp
            - first_note
        next_action:
          type: string
          description: Setup guidance for an assistant, present only while setup is incomplete and a first note is the gap.
    AgentGrantInfo:
      type: object
      description: One folder an agent token was given.
      required:
      - container_id
      - name
      - team_id
      - level
      - effective
      properties:
        container_id:
          type: integer
        name:
          type: string
          description: The folder's name, or for a space's root the team's name or "Personal".
        team_id:
          type:
          - integer
          - 'null'
        level:
          type: string
          enum:
          - read
          - write
          description: What was granted. Everything below the folder inherits it unless another grant says otherwise.
        effective:
          type: string
          enum:
          - none
          - read
          - write
          description: What the token can do there now, after the person's own role caps it.
    TeamMembershipInfo:
      type: object
      required:
      - id
      - name
      - role
      - notes_used
      - notes_limit
      properties:
        id:
          type: integer
        name:
          type: string
        role:
          type: string
          enum:
          - owner
          - member
        notes_used:
          type: integer
        notes_limit:
          type:
          - integer
          - 'null'
          description: Null when the team has no limit.
    MeToken:
      type: object
      description: 'The token making the request. `instructions`, `follows_brain_instructions` and `grants` appear only for an agent token (`restricted: true`).'
      required:
      - id
      - name
      - restricted
      - scope_container
      properties:
        id:
          type: integer
        name:
          type: string
        restricted:
          type: boolean
          description: True for an agent token, which reaches only its grants.
        scope_container:
          description: 'Kept for older clients: the folder when the token holds exactly one grant and it is write, otherwise null. Read `grants` instead.'
          oneOf:
          - $ref: '#/components/schemas/ContainerRef'
          - type: 'null'
        instructions:
          type: string
          description: What the person wrote for this agent; an empty string when nothing.
        follows_brain_instructions:
          type: boolean
          description: Whether this agent should also follow the person's brain-wide instructions (the API does not serve those to agent tokens).
        grants:
          type: array
          items:
            $ref: '#/components/schemas/AgentGrantInfo'
  responses:
    TooManyRequests:
      description: Over the rate limit of 100 requests a minute per account, counted across all of its tokens (counters are kept per server process, so the ceiling actually enforced can be somewhat higher). Wait the number of seconds in `Retry-After`. The body has `error` only.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Rate limit exceeded. Retry after 12 seconds.
    Unauthorized:
      description: The bearer token is missing, unknown or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Unauthorized
            code: unauthorized
            message: 'Missing or invalid token. Send it as Authorization: Bearer <token>; tokens are created in Settings > Connections.'
            docs_url: https://hjarni.com/docs/api#auth
  headers:
    Retry-After:
      description: Seconds until the current rate-limit window ends.
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'An API token in `Authorization: Bearer <token>`. Tokens are created in Settings > Connections, or issued to an assistant through the OAuth flow. A new token made in Settings reaches only the folders it is given, at Read or Write per folder, unless it is made with Everything I can reach (see https://hjarni.com/docs/agent-tokens); a token issued through OAuth acts with the person''s full access. A missing, unknown or expired token answers 401.'
externalDocs:
  url: https://hjarni.com/docs/api