openapi: 3.2.0
info:
  title: Opoint Agreements API
  version: 1.0.0
  description: 'Operations tagged agreements across 2 of this provider''s published API definitions: opoint-openapi-original.yml, opoint-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.opoint.com
tags:
- name: Agreements
paths:
  /agreements/:
    get:
      operationId: agreements_list
      description: An agreement is one site tag's sites and single sources, on one licence configuration. It is named by its tag, so agreements on one tag share a name; `label` tells them apart. Agreements are edited in the toolkit, not through the API.
      summary: List agreements
      parameters:
      - in: query
        name: search_string
        schema:
          type: string
        description: Search for agreements by name or description
      tags:
      - Agreements
      security:
      - JWT: []
      - ephmeralId: []
      - staticToken: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgreementList'
          description: ''
    servers:
    - url: https://api.opoint.com
  /agreements/{id}:
    get:
      operationId: agreements_retrieve
      description: The agreement with its site tag (and the other agreements on it), its licence configuration (and the other agreements sharing it), and any scoped configurations. Its sites and sources are listed by the `sites` and `sources` endpoints.
      summary: Agreement's detail
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      tags:
      - Agreements
      security:
      - JWT: []
      - ephmeralId: []
      - staticToken: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agreement'
          description: ''
    servers:
    - url: https://api.opoint.com
  /agreements/{id}/sites:
    get:
      operationId: agreements_sites_list
      description: The sites on the agreement's tag, by name.
      summary: Agreement's sites
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      - in: query
        name: search
        schema:
          type: string
        description: Only those whose name contains this
      tags:
      - Agreements
      security:
      - JWT: []
      - ephmeralId: []
      - staticToken: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgreementSite'
          description: ''
    servers:
    - url: https://api.opoint.com
  /agreements/{id}/sources:
    get:
      operationId: agreements_sources_list
      description: Sources the agreement grants on their own, on top of its sites, for when only part of a site is covered.
      summary: Agreement's single sources
      parameters:
      - in: path
        name: id
        schema:
          type: integer
        required: true
      - in: query
        name: search
        schema:
          type: string
        description: Only those whose name contains this
      tags:
      - Agreements
      security:
      - JWT: []
      - ephmeralId: []
      - staticToken: []
      - cookieAuth: []
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgreementSource'
          description: ''
    servers:
    - url: https://api.opoint.com
components:
  schemas:
    AgreementList:
      type: object
      properties:
        id_agreement:
          type: integer
          readOnly: true
        name:
          type: string
          readOnly: true
          description: The site tag's name. Agreements on one tag share it; when exposed, customers see it as the licence name of its sites.
        label:
          type: string
          readOnly: true
          description: The name followed by the licence configuration's name, which tells same-named agreements apart.
        description:
          type:
          - string
          - 'null'
          readOnly: true
        priority:
          type: integer
          readOnly: true
          description: '1 or more: the licence configuration overrides the sites'' own licences. 0: the two are combined.'
        expose:
          type: boolean
          readOnly: true
          description: Whether customers see the name as the licence name of its sites.
        tag:
          oneOf:
          - $ref: '#/components/schemas/AgreementTagRef'
          - type: 'null'
          readOnly: true
        licence_configuration:
          oneOf:
          - $ref: '#/components/schemas/LicenseConfigurationRef'
          - type: 'null'
          readOnly: true
          description: null when the agreement only grants access, and the sites' own licences apply.
        site_count:
          type: integer
          readOnly: true
        source_count:
          type: integer
          readOnly: true
          description: Single sources, on top of the sites.
        customers:
          type: integer
          readOnly: true
          description: Customers with an active, non-staff user holding the agreement, of their own or inherited. Counted hourly.
        created:
          type: string
          format: date-time
          readOnly: true
        last_change:
          type: string
          format: date-time
          readOnly: true
      required:
      - created
      - customers
      - description
      - expose
      - id_agreement
      - label
      - last_change
      - licence_configuration
      - name
      - priority
      - site_count
      - source_count
      - tag
    AgreementAccessGroup:
      type: object
      properties:
        access_groups:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
        name:
          type: string
          maxLength: 255
      required:
      - access_groups
    Agreement:
      type: object
      properties:
        id_agreement:
          type: integer
          readOnly: true
        name:
          type: string
          readOnly: true
          description: The site tag's name. Agreements on one tag share it; when exposed, customers see it as the licence name of its sites.
        label:
          type: string
          readOnly: true
          description: The name followed by the licence configuration's name, which tells same-named agreements apart.
        description:
          type:
          - string
          - 'null'
          readOnly: true
        priority:
          type: integer
          readOnly: true
          description: '1 or more: the licence configuration overrides the sites'' own licences. 0: the two are combined.'
        expose:
          type: boolean
          readOnly: true
          description: Whether customers see the name as the licence name of its sites.
        tag:
          oneOf:
          - $ref: '#/components/schemas/AgreementTag'
          - type: 'null'
          readOnly: true
        licence_configuration:
          oneOf:
          - $ref: '#/components/schemas/LicenseConfiguration'
          - type: 'null'
          readOnly: true
          description: null when the agreement only grants access, and the sites' own licences apply.
        site_count:
          type: integer
          readOnly: true
        source_count:
          type: integer
          readOnly: true
          description: Single sources, on top of the sites.
        customers:
          type: integer
          readOnly: true
          description: Customers with an active, non-staff user holding the agreement, of their own or inherited. Counted hourly.
        created:
          type: string
          format: date-time
          readOnly: true
        last_change:
          type: string
          format: date-time
          readOnly: true
        scoped_licence_configurations:
          type: array
          items:
            $ref: '#/components/schemas/ScopedLicenseConfiguration'
          readOnly: true
          description: Configurations linked with a scope. Not evaluated anywhere yet.
      required:
      - created
      - customers
      - description
      - expose
      - id_agreement
      - label
      - last_change
      - licence_configuration
      - name
      - priority
      - scoped_licence_configurations
      - site_count
      - source_count
      - tag
    ScopedLicenseConfiguration:
      type: object
      properties:
        scope:
          type: string
          readOnly: true
        licence_configuration:
          allOf:
          - $ref: '#/components/schemas/LicenseConfigurationRef'
          readOnly: true
      required:
      - licence_configuration
      - scope
    SummarizerParamField:
      type: object
      description: Serializer describing the SummarizerParamField
      properties:
        type:
          type: integer
        number_of_sentences:
          type: integer
        max_percentage_of_characters_to_show:
          type: integer
        max_number_of_words_to_show:
          type: integer
      required:
      - max_number_of_words_to_show
      - max_percentage_of_characters_to_show
      - number_of_sentences
      - type
    AgreementRef:
      type: object
      description: 'An agreement mentioned by another: on the same tag, or sharing a configuration.'
      properties:
        id_agreement:
          type: integer
          readOnly: true
        name:
          type: string
          readOnly: true
          description: The agreement's site tag's name.
        label:
          type: string
          readOnly: true
          description: The name followed by the licence configuration's name, which tells same-named agreements apart.
      required:
      - id_agreement
      - label
      - name
    LicenseConfigurationRef:
      type: object
      properties:
        id_license_configuration:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 255
      required:
      - id_license_configuration
    SummarizerParam:
      type: object
      properties:
        license:
          $ref: '#/components/schemas/SummarizerParamField'
        report_license:
          $ref: '#/components/schemas/SummarizerParamField'
        mail_license:
          $ref: '#/components/schemas/SummarizerParamField'
        share_license:
          $ref: '#/components/schemas/SummarizerParamField'
      required:
      - license
      - mail_license
      - report_license
      - share_license
    LicenseConfiguration:
      type: object
      properties:
        id_license_configuration:
          type: integer
          readOnly: true
        name:
          type: string
          readOnly: true
        description:
          type:
          - string
          - 'null'
          readOnly: true
        summarizer_param:
          oneOf:
          - $ref: '#/components/schemas/SummarizerParam'
          - type: 'null'
          readOnly: true
        max_archive_age:
          type:
          - integer
          - 'null'
          readOnly: true
        max_free_search_age:
          type:
          - integer
          - 'null'
          readOnly: true
        licence:
          type: integer
          readOnly: true
        licence_share:
          type: integer
          readOnly: true
        licence_mail:
          type: integer
          readOnly: true
        licence_report:
          type: integer
          readOnly: true
        licence_enforce:
          type: integer
          readOnly: true
        licence_enforce_share:
          type: integer
          readOnly: true
        licence_enforce_mail:
          type: integer
          readOnly: true
        licence_enforce_report:
          type: integer
          readOnly: true
        created:
          type: string
          format: date-time
          readOnly: true
        last_change:
          type: string
          format: date-time
          readOnly: true
        agreements:
          type: array
          items:
            $ref: '#/components/schemas/AgreementRef'
          readOnly: true
          description: Every agreement using this configuration. Editing it changes them all.
      required:
      - agreements
      - created
      - description
      - id_license_configuration
      - last_change
      - licence
      - licence_enforce
      - licence_enforce_mail
      - licence_enforce_report
      - licence_enforce_share
      - licence_mail
      - licence_report
      - licence_share
      - max_archive_age
      - max_free_search_age
      - name
      - summarizer_param
    AgreementTagRef:
      type: object
      properties:
        id_sitetag:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 255
        access_group:
          oneOf:
          - $ref: '#/components/schemas/AgreementAccessGroup'
          - type: 'null'
          readOnly: true
          description: The legacy access group kept in step with this tag, if any. One tag has one at most.
      required:
      - access_group
      - id_sitetag
      - name
    AgreementSource:
      type: object
      properties:
        id_source:
          type: integer
          readOnly: true
        name:
          type: string
          readOnly: true
        url:
          type: string
          readOnly: true
        id_site:
          type: integer
          readOnly: true
      required:
      - id_site
      - id_source
      - name
      - url
    AgreementTag:
      type: object
      properties:
        id_sitetag:
          type: integer
          readOnly: true
        name:
          type: string
          maxLength: 255
        access_group:
          oneOf:
          - $ref: '#/components/schemas/AgreementAccessGroup'
          - type: 'null'
          readOnly: true
          description: The legacy access group kept in step with this tag, if any. One tag has one at most.
        agreements:
          type: array
          items:
            $ref: '#/components/schemas/AgreementRef'
          readOnly: true
          description: Every agreement on this tag. Its sites and sources are theirs too.
      required:
      - access_group
      - agreements
      - id_sitetag
      - name
    AgreementSite:
      type: object
      properties:
        id_site:
          type: integer
          readOnly: true
        name:
          type: string
          readOnly: true
        url:
          type:
          - string
          - 'null'
          readOnly: true
      required:
      - id_site
      - name
      - url
  securitySchemes:
    JWT:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "JWT"
    cookieAuth:
      type: apiKey
      in: cookie
      name: PHPSESSID
    ephmeralId:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Ephemeral"
    staticToken:
      type: apiKey
      in: header
      name: Authorization
      description: Token-based authentication with required prefix "Token"
x-refined-from:
- opoint-openapi-original.yml
- opoint-openapi.yml