openapi: 3.1.1
info:
  title: Claromentis InfoCapture API
  version: 1.0.0
  description: Rest API for Claromentis InfoCapture
  contact:
    name: Discover Claromentis
    url: https://discover.claromentis.com
externalDocs:
  description: Learn more about Claromentis APIs
  url: https://developer.claromentis.com
servers:
  - url: '{protocol}{hostname}/api/infocapture/v1'
    variables:
      protocol:
        enum:
          - https://
          - http://
        default: https://
      hostname:
        default: 'yourintranet.com'
        description: Claromentis Server Hostname
tags:
  - name: Projects
    description: Infocapture projects
  - name: Issues
    description: Infocapture issues
paths:
  /projects:
    get:
      summary: List projects
      description: List InfoCapture projects
      parameters:
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/project_status'
      responses:
        "200":
          $ref: '#/components/responses/Projects'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
      tags:
        - Projects
  /projects/{project-id}:
    get:
      summary: Get a project
      description: Get an InfoCapture project by ID
      parameters:
        - $ref: '#/components/parameters/project-id'
      responses:
        "200":
          $ref: '#/components/responses/Project'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
      tags:
        - Projects
  /projects/{project-id}/issues:
    get:
      summary: List project issues
      description: List a project’s issues by project ID
      parameters:
        - $ref: '#/components/parameters/project-id'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
        - $ref: '#/components/parameters/reporter'
        - $ref: '#/components/parameters/assignee'
        - $ref: '#/components/parameters/created_from'
        - $ref: '#/components/parameters/last_modified'
        - $ref: '#/components/parameters/archived'
        - $ref: '#/components/parameters/monitoring'
        - $ref: '#/components/parameters/status'
      responses:
        "200":
          $ref: '#/components/responses/Issues'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
      tags:
        - Projects
  /projects/{project-id}/issues/{issue-iid}:
    get:
      summary: Get a project issue by internal ID
      description: Get a project issue by its project ID and internal issue ID
      parameters:
        - $ref: '#/components/parameters/project-id'
        - $ref: '#/components/parameters/issue-iid'
      responses:
        "200":
          $ref: '#/components/responses/Issue'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
      tags:
        - Projects
#  /issues:
#    get:
#      summary: List issues
#      description: List InfoCapture issues across all projects
#      parameters:
#        - $ref: '#/components/parameters/limit'
#        - $ref: '#/components/parameters/offset'
#        - $ref: '#/components/parameters/reporter'
#        - $ref: '#/components/parameters/assignee'
#        - $ref: '#/components/parameters/created_from'
#        - $ref: '#/components/parameters/last_modified'
#        - $ref: '#/components/parameters/archived'
#        - $ref: '#/components/parameters/monitoring'
#        - $ref: '#/components/parameters/status'
#      responses:
#        200:
#          $ref: '#/components/responses/Issues'
#        401:
#          $ref: '#/components/responses/Unauthorized'
#        404:
#          $ref: '#/components/responses/NotFound'
#      tags:
#        - Issues
  /issues/{issue-id}:
    get:
      summary: Get an issue
      description: Get an issue by its unique ID
      parameters:
        - $ref: '#/components/parameters/issue-id'
      responses:
        "200":
          $ref: '#/components/responses/Issue'
        "401":
          $ref: '#/components/responses/Unauthorized'
        "404":
          $ref: '#/components/responses/NotFound'
      tags:
        - Issues
components:
  parameters:
    project-id:
      name: id
      in: path
      description: Unique project ID
      schema:
        type: integer
        minimum: 0
        example: 1
      required: true
    issue-id:
      name: id
      in: path
      description: Unique issue ID
      schema:
        type: integer
        minimum: 0
        example: 1
      required: true
    issue-iid:
      name: iid
      in: path
      description: Internal issue ID (`iid`) within a project.
      schema:
        type: integer
        minimum: 0
        example: 1
      required: true
    limit:
      name: limit
      in: query
      description: The number of items to return
      schema:
        type: integer
        minimum: 1
        maximum: 200
        default: 20
    offset:
      name: offset
      in: query
      description: The number of items to offset results by
      schema:
        type: integer
        minimum: 0
        default: 0
    reporter:
      name: reporter
      in: query
      description: Comma-separated list of reporter IDs to filter by
      schema:
        type: array
        items:
          type: integer
        explode: false
    assignee:
      name: assignee
      in: query
      description: Comma-separated list of assignee users IDs to filter by
      schema:
        type: array
        items:
          type: integer
        explode: false
    created_from:
      name: created_from
      in: query
      description: Filter from created date
      schema:
        type: string
        example: "2026-01-01"
    last_modified:
      name: last_modified
      in: query
      description: Filter from modified date
      schema:
        type: string
        format: date
        example: "2026-01-01"
    archived:
      name: archived
      in: query
      description: Only show archived issues (`true`), or unarchived issues (`false`). Show all issues when empty.
      schema:
        type: boolean
    monitoring:
      name: monitoring
      in: query
      description: Only show issues that the current user is monitoring
      schema:
        type: boolean
    status:
      name: status
      in: query
      description: Issue status filter, if enabled for the project. Default project statuses are `'new'`, `'progress'`, and `'closed'`.
      schema:
        type: string
    project_status:
      name: status
      in: query
      description: Project status filter. `'active'`, `'blocked'`, `'testing'`, or empty value for no filter.
      schema:
        type: string
        enum:
          - active
          - blocked
          - testing
  schemas:
    Project:
      description: Project object
      properties:
        id:
          type: integer
          description: ID of the project
          examples:
            - 123
          readOnly: true
        name:
          type: string
          description: Project's name
          examples:
            - "Issue tracker"
          readOnly: true
        description:
          type: string
          description: Project's description, usually describing the purpose of the project
          examples:
            - 'Software issue tracker system'
          readOnly: true
        status:
          $ref: '#/components/schemas/ProjectStatus'
        project_icon:
          type: string
          description: Project's icon
          examples:
            - "glyphicons-notes-2"
          readOnly: true
        project_icon_color:
          type: string
          format: color
          description: Project icon's hexadecimal color code
          readOnly: true
        description_simple:
          type: string
          description: Short project description
          readOnly: true
        description_rich:
          type: string
          description: Full project description
          readOnly: true
        handle_incoming_mail:
          type: bool
          description: Whether the project handles incoming emails for creating issues
          readOnly: true
        from_address:
          type: string
          format: email
          description: The "From" address to use for outbound emails for the project
          readOnly: true
        statuses_enabled:
          type: bool
          description: Whether the project has issue statuses enabled
          readOnly: true
        assigned_enabled:
          type: bool
          description: Whether the project's issues can be assigned to users
          readOnly: true
        likes_enabled:
          type: bool
          description: Whether likes are enabled for project issues
          readOnly: true
        external_submission_enabled:
          type: bool
          description: Whether external submissions from guest users are enabled for the project
          readOnly: true
        issues_id_prefix:
          type: string
          description: Prefix for issue IDs
          readOnly: true
          examples:
            - EXAMPLE
        codename:
          type: string
          description: Project codename
          readOnly: true
        primary_field:
          type:
            - string
            - "null"
          description: Primary field symname for the project's issues
          readOnly: true
        plugin_name:
          type: string
          description: InfoCapture plugin name
          readOnly: true
        tags:
          type: array
          description: Project's assigned tags
          readOnly: true
          items:
            $ref: '#/components/schemas/Tag'
        statuses:
          type: array
          description: Project's available issue statuses
          readOnly: true
          items:
            $ref: '#/components/schemas/IssueStatus'
        url:
          description: Project's web URL
          type: string
          readOnly: true
          examples:
            - "https://yourintranet.com/intranet/infocapture/project.php?project_id=123"
        issues_url:
          description: API URL for retrieving the project's issues
          type: string
          readOnly: true
          examples:
            - "https://yourintranet.com/api/infocapture/v1/projects/123/issues"
    Issue:
      description: Issue object
      properties:
        id:
          type: integer
          description: Unique issue ID
          readOnly: true
        iid:
          type: integer
          description: Internal issue ID, unique per-project
          examples:
            - 00123
          readOnly: true
        id_prefixed:
          type: string
          description: Zero-padded unique issue ID (`id`), or prefixed internal issue ID (`iid`) if an issue prefix is set for its project
          examples:
            - 000123
            - EXAMPLE0001
          readOnly: true
        project_id:
          type: integer
          description: ID of the project
          examples:
            - 123
          readOnly: true
        reporter:
          $ref: '#/components/schemas/User'
          description: Reporter user object
          readOnly: true
        assigned:
          $ref: '#/components/schemas/User'
          description: Assigned user to the issue
        status:
          type: string
          description: Issue status code, from a project's list of issue statuses
          examples:
            - "new"
            - "progress"
            - "closed"
        traffic_light:
          type:
            - string
            - "null"
          description: Issue's current traffic light
          readOnly: true
        date_of_report:
          type: string
          format: date-time
          description: Reported date
          readOnly: true
        last_modified:
          type: string
          format: date-time
          description: Last modified date
          readOnly: true
        fields:
          description: Issue form data display values, keyed field symname
          type: object
          examples:
            - test_field: Test value
            - another_field: Another value
        history:
          description: Issue history entries
          type: array
          items:
            $ref: '#/components/schemas/IssueHistoryEntry'
          readOnly: true
        issue_url:
          type: string
          description: URL of the issue
          examples:
            - https://yourintranet.com/forms/api_test/view/1162
          readOnly: true
        permalink:
          type: string
          description: Permanent issue URL
          examples:
            - https://yourintranet.com/intranet/infocapture/view_issue.php?id=6
          readOnly: true
    ProjectStatus:
      type: object
      description: Project status
      properties:
        id:
          type: integer
          description: ID of the project's status
          examples:
            - 1
          readOnly: true
        name:
          type: string
          description: Project's status name
          examples:
            - "Active"
          readOnly: true
    IssueStatus:
      type: object
      description: Issue status
      properties:
        code:
          type: string
          description: Issue status code
          examples:
            - "new"
            - "progress"
            - "closed"
          readOnly: true
        label:
          type: string
          description: Issue status label
          examples:
            - "New"
          readOnly: true
        description:
          type: string
          description: Issue status description
          examples:
            - "New ticket"
          readOnly: true
        color:
          type: string
          description: Issue status's hexadecimal color code
          examples:
            - "fff0f0"
          readOnly: true
        archives:
          type: bool
          description: Whether issues in the status are archived automatically, after `archive_idle_time` days
        archive_idle_time:
          type: integer
          description: Number of days after which issues in the status are archived
    IssueHistoryEntry:
      type: object
      description: Issue history entry
      readOnly: true
      properties:
        id:
          type: integer
          description: Unique ID of the issue history entry
          examples:
            - 456
        #        iid: # TODO
        #          type: string
        #          description: Internal ID of the issue history entry
        #          examples:
        #            - "123.4"
        date:
          type: string
          format: date-time
          description: Date-time of the history entry.
        user:
          $ref: '#/components/schemas/User'
          description: Acting user that caused the changes
        field:
          type: string
          description: Display name of the field that changed
          examples:
            - Status
            - Assigned to
        symname:
          type: string
          description: Symname of the field that changed
          examples:
            - _status_
            - _assigned_
        changes:
          type: object
          description: Changes that occurred
          properties:
            from:
              type: string
              description: Previous value
              examples:
                - "New"
                - "In progress"
                - "Closed"
                - "Old value"
            to:
              type: string
              description: New value
              examples:
                - "New"
                - "In progress"
                - "Closed"
                - "New value"
    #            duration: # TODO
    #              type: integer
    #              description: Duration in the status since this history entry, if the status field changed
    #              examples:
    #                - 50804963
    Tag:
      type: string
      description: System tag
    User:
      description: Claromentis user
      type: object
      properties:
        id:
          type: integer
          description: User ID
          examples:
            - 123
          readOnly: true
        name:
          type: string
          description: User's full name
          examples:
            - "John Doe"
          readOnly: true
        url:
          type: string
          description: People API URL for the user
          examples:
            - "https://yourintranet.com/api/people/v2/users/123"
    Pagination:
      description: Standard pagination object
      properties:
        offset:
          type: integer
          description: The number of items results are offset by
          minimum: 0
          readOnly: true
        limit:
          type: integer
          description: The number of items returned
          minimum: 1
          maximum: 20
          readOnly: true
        total:
          type: integer
          description: The total number of items
          examples:
            - 100
          readOnly: true
        prev:
          type:
            - string
            - "null"
          description: URL to the previous page of items
          readOnly: true
        next:
          type:
            - string
            - "null"
          description: URL to the next page of items
          readOnly: true
  responses:
    Issue:
      description: The issue returned by ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Issue'
    Issues:
      description: The list of issues from project
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Issue'
              pagination:
                $ref: '#/components/schemas/Pagination'
    Project:
      description: The project returned by ID
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Project'
    Projects:
      description: The list of projects
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
              pagination:
                $ref: '#/components/schemas/Pagination'
    Unauthorized:
      description: Authentication is required
      content:
        application/json:
          schema:
            type: object
            description: Authentication is required
            properties:
              error:
                type: boolean
                description: The error flag
                readOnly: true
              message:
                type: string
                description: The error message
                examples:
                  - "Authentication required"
                readOnly: true
              code:
                type: integer
                description: The HTTP response status code
                examples:
                  - 401
                readOnly: true
    NotFound:
      description: The returned object was not found
      content:
        application/json:
          schema:
            type: object
            description: Response object when project or issue does not exist
            properties:
              error:
                type: boolean
                description: The error flag
                readOnly: true
              message:
                type: string
                description: The error message
                readOnly: true
              code:
                type: integer
                description: The HTTP response status code
                readOnly: true
          examples:
            projectNotFound:
              value:
                error: true
                message: Project not found
                code: 404
            issueNotFound:
              value:
                error: true
                message: Issue not found
                code: 404
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
