openapi: 3.0.3
info:
  title: TriplyDB Accounts API
  version: 26.5.104
  description: "REST API for TriplyDB — a linked data database platform.\n\n## Authentication\n\nRead operations on publicly published datasets can be performed without\nauthentication. Write operations and read operations on private or internal\ndatasets require a valid API token.\n\n### Creating an API token\n\n1. Log into your TriplyDB instance.\n2. Click on the user menu in the top-right corner and click on \"User settings\".\n3. Go to the \"API tokens\" tab.\n4. Click \"Create token\", enter a description (e.g., \"my-script\") and select\n   the appropriate access rights.\n5. Click \"Create\" and copy the token. It is only shown once upon creation.\n\n### Using the API token\n\nInclude the token in the `Authorization` header of your HTTP requests:\n\n```\nAuthorization: Bearer YOUR_TOKEN\n```\n\n### Security considerations\n\n- **Do not commit tokens to git repositories.**\n- **Do not share tokens** with anyone who should not have access to your\n  TriplyDB resources.\n- **Rotate tokens regularly**, especially if you suspect a compromise.\n\n## Pagination\n\nList endpoints are paginated. The response includes a `Link` header\n([RFC 8288](https://www.rfc-editor.org/rfc/rfc8288)) with URLs for\nnavigating the result set. To paginate, follow the URLs in the `Link`\nheader rather than constructing URLs manually.\n\nThe `Link` header contains up to three relations:\n\n| Relation | Meaning |\n|----------|---------|\n| `first`  | URL to the first page of results |\n| `next`   | URL to the next page (absent when on the last page) |\n| `prev`   | URL to the previous page (absent when on the first page) |\n\nExample response header:\n\n```\nLink: <https://api.example.com/datasets/user/ds?limit=30>; rel=\"first\",\n      <https://api.example.com/datasets/user/ds?since=6435a&limit=30>; rel=\"next\"\n```\n\nTo iterate through all results, keep following the `rel=\"next\"` URL until\nit is no longer present. You can control the page size with the `limit`\nquery parameter (default: 30).\n\n## Content negotiation\n\nLinked data endpoints support format negotiation in two ways:\n\n1. **Accept header** — set the `Accept` request header to the desired media type.\n2. **URL extension** — append a format extension to the URL path (e.g., `/run.csv`).\n   When present, the extension takes precedence over the `Accept` header.\n"
  contact:
    name: Triply
    url: https://triply.cc
servers:
- url: https://api.lod.uba.uva.nl
  description: This instance
security:
- bearerAuth: []
- {}
tags:
- name: Accounts
  description: Account and group management
paths:
  /accounts:
    get:
      tags:
      - Accounts
      summary: List accounts
      operationId: listAccounts
      parameters:
      - $ref: '#/components/parameters/limit'
      - name: offset
        in: query
        schema:
          type: integer
      - name: q
        in: query
        description: Search term
        schema:
          type: string
      - name: sortBy
        in: query
        schema:
          type: string
          enum:
          - accountNameLower
          - createdAt
          - updatedAt
      - $ref: '#/components/parameters/sortDirection'
      - name: type
        in: query
        schema:
          $ref: '#/components/schemas/AccountType'
      responses:
        '200':
          description: Paginated account list
          headers:
            Link:
              $ref: '#/components/headers/Link'
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Account'
  /me:
    get:
      tags:
      - Accounts
      summary: Get current user
      operationId: getMe
      responses:
        '200':
          description: Current user details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
    patch:
      tags:
      - Accounts
      summary: Update current user
      operationId: updateMe
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdate'
      responses:
        '200':
          description: Updated user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Accounts
      summary: Delete current user
      operationId: deleteMe
      responses:
        '204':
          description: Account deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{account}:
    parameters:
    - $ref: '#/components/parameters/account'
    get:
      tags:
      - Accounts
      summary: Get an account by name
      operationId: getAccount
      security:
      - {}
      parameters:
      - name: verbose
        in: query
        schema:
          type: string
      responses:
        '200':
          description: Account details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      tags:
      - Accounts
      summary: Update an account
      operationId: updateAccount
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AccountUpdate'
      responses:
        '200':
          description: Updated account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    delete:
      tags:
      - Accounts
      summary: Delete an account
      operationId: deleteAccount
      responses:
        '204':
          description: Account deleted
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
  /accounts/{account}/members:
    parameters:
    - $ref: '#/components/parameters/account'
    get:
      tags:
      - Accounts
      summary: List group members
      operationId: listMembers
      responses:
        '200':
          description: Member list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/GroupMember'
    post:
      tags:
      - Accounts
      summary: Add a member to a group
      operationId: addMember
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - accountName
              - role
              properties:
                accountName:
                  type: string
                role:
                  $ref: '#/components/schemas/GroupRole'
      responses:
        '201':
          description: Member added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMember'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /accounts/{account}/members/{member}:
    parameters:
    - $ref: '#/components/parameters/account'
    - $ref: '#/components/parameters/member'
    get:
      tags:
      - Accounts
      summary: Get member details
      operationId: getMember
      responses:
        '200':
          description: Member details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMember'
    patch:
      tags:
      - Accounts
      summary: Update member role
      operationId: updateMember
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - role
              properties:
                role:
                  $ref: '#/components/schemas/GroupRole'
      responses:
        '200':
          description: Updated member
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupMember'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      tags:
      - Accounts
      summary: Remove a member from a group
      operationId: removeMember
      responses:
        '204':
          description: Member removed
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    AccountType:
      type: string
      enum:
      - user
      - org
    Org:
      allOf:
      - $ref: '#/components/schemas/Account'
      - type: object
        properties:
          type:
            type: string
            enum:
            - org
          members:
            type: array
            items:
              $ref: '#/components/schemas/GroupMember'
    GroupRole:
      type: string
      description: Group role identifier (e.g. "owner", "member", or a custom role id)
      example: member
    GroupMember:
      type: object
      required:
      - role
      - user
      - createdAt
      - updatedAt
      properties:
        role:
          $ref: '#/components/schemas/GroupRole'
        user:
          readOnly: true
          allOf:
          - $ref: '#/components/schemas/User'
        createdAt:
          type: string
          format: date-time
          readOnly: true
        updatedAt:
          type: string
          format: date-time
          readOnly: true
    AccountUpdate:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
          format: email
        accountName:
          type: string
        description:
          type: string
        pinnedItems:
          type: array
          items:
            type: object
    User:
      allOf:
      - $ref: '#/components/schemas/Account'
      - type: object
        properties:
          type:
            type: string
            enum:
            - user
          orgs:
            type: array
            items:
              $ref: '#/components/schemas/Org'
          authMethod:
            type: string
          verified:
            type: boolean
          mfaEnabled:
            type: boolean
          legalConsent:
            type: string
            enum:
            - ok
            - expiring
            - expired
            - unset
    ErrorResponse:
      type: object
      required:
      - message
      properties:
        message:
          type: string
          example: Resource not found.
        code:
          type: integer
          example: 404
        errors:
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponse'
    Account:
      type: object
      discriminator:
        propertyName: type
        mapping:
          user: '#/components/schemas/User'
          org: '#/components/schemas/Org'
      required:
      - accountName
      - uid
      - createdAt
      - description
      - type
      properties:
        accountName:
          type: string
          example: acme-research
        uid:
          type: string
          readOnly: true
          example: 64a1b2c3d4e5f60012345678
        name:
          type: string
          example: ACME Research Lab
        description:
          type: string
          example: Publishing linked open data for the sciences.
        avatarUrl:
          type: string
          readOnly: true
        createdAt:
          type: string
          format: date-time
          readOnly: true
          example: 2024-01-15 10:30:00+00:00
        updatedAt:
          type: string
          format: date-time
          readOnly: true
        type:
          $ref: '#/components/schemas/AccountType'
        accountType:
          type: string
          enum:
          - user
          - group
          readOnly: true
        pinnedItems:
          type: array
          items:
            type: object
        datasetCount:
          type: integer
          readOnly: true
        queryCount:
          type: integer
          readOnly: true
        storyCount:
          type: integer
          readOnly: true
        email:
          type: string
          format: email
  parameters:
    sortDirection:
      name: sortDirection
      in: query
      description: Sort direction
      schema:
        type: string
        enum:
        - asc
        - desc
    account:
      name: account
      in: path
      required: true
      description: Account name (user or group)
      schema:
        type: string
    limit:
      name: limit
      in: query
      description: Maximum number of results
      schema:
        type: integer
        minimum: 1
    member:
      name: member
      in: path
      required: true
      description: Member account name
      schema:
        type: string
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Authentication required
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  headers:
    Link:
      description: 'RFC 8288 pagination links. Contains `rel="first"` and `rel="next"`

        URIs for cursor-based pagination.

        '
      schema:
        type: string
        example: <https://api.triplydb.com/datasets?limit=20>; rel="first", <https://api.triplydb.com/datasets?since=64a1b2c3d4e5f60012345678&limit=20>; rel="next"
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT