ECMWF Data Stores Profile API

openapi: 3.1.0
info:
  title: ECMWF Data Stores Profile API
  summary: REST API to handle user authentication and users' data (authentication
    from both OIDC and PAT, permissions, licences management, etc.)
  version: 0.1.0
paths:
  /metrics:
    get:
      summary: Handle Metrics
      description: "A handler to expose Prometheus metrics\nExample usage:\n\n   \
        \ ```\n    app.add_middleware(PrometheusMiddleware)\n    app.add_route(\"\
        /metrics\", handle_metrics)\n    ```"
      operationId: handle_metrics_metrics_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
  /account/licences:
    get:
      tags:
      - account
      summary: Get Licences
      description: Get current logged-in user's licences.
      operationId: get_licences_account_licences_get
      parameters:
      - name: scope
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/LicenceScopeCriterion'
          default: all
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Licences'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - account
      summary: Accept Licences
      description: Accept user licences.
      operationId: accept_licences_account_licences_patch
      parameters:
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicencesData'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Licences'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /account/licences/{licence_uid}:
    put:
      tags:
      - account
      summary: Accept Licence
      description: 'Accept a user licence.


        This always accept the newest revision of the licence.'
      operationId: accept_licence_account_licences__licence_uid__put
      parameters:
      - name: licence_uid
        in: path
        required: true
        schema:
          type: string
          title: Licence Uid
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LicenceData'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Licence'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /account/verification/pat:
    post:
      tags:
      - account
      summary: Verify Personal Api Token
      description: Endpoint to verify a user's PAT.
      operationId: Verify_Personal_API_Token_account_verification_pat_post
      parameters:
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MinimalUserInfo'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /account/verification/oidc:
    post:
      tags:
      - account
      summary: Verify Oidc Token
      description: Endpoint to verify a user's JWT token.
      operationId: Verify_OIDC_Token_account_verification_oidc_post
      parameters:
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MinimalUserInfo'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /account/pat:
    get:
      tags:
      - account
      summary: Get Personal Api Token
      description: Get current logged-in user's PAT.
      operationId: Get_personal_API_Token_account_pat_get
      parameters:
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPAT'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - account
      summary: Generate A New Personal Api Token
      description: 'Generate a new user PAT.


        Can be only called from Web user interface.'
      operationId: Generate_a_new_personal_API_Token_account_pat_put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserPAT'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /account/:
    get:
      tags:
      - account
      summary: Get Account Data
      description: Get current logged-in user's data.
      operationId: get_account_data_account__get
      parameters:
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    patch:
      tags:
      - account
      summary: Update Account
      description: Update current logged-in user's data.
      operationId: update_account_account__patch
      parameters:
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserData'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - account
      summary: Create Account
      description: Create a new user.
      operationId: create_account_account__post
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserCreationData'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - account
      summary: Synchronize Oidc User'S Data With Ecmwf Data Stores Database
      description: 'Refresh OIDC user''s data on ECMWF Data Stores database.


        This is not a standard RESTful PUT method, but designed for internal purposes.

        To update user''s information, use PATCH method instead.'
      operationId: Synchronize_OIDC_user_s_data_with_ECMWF_Data_Stores_database_account__put
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UserInfo'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /account/starred:
    post:
      tags:
      - account
      summary: Star
      description: Add a dataset to favourites.
      operationId: star_account_starred_post
      parameters:
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Dataset'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                title: Response Star Account Starred Post
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /account/starred/{dataset}:
    delete:
      tags:
      - account
      summary: Delete Starred
      description: Remove a dataset from favourites.
      operationId: delete_starred_account_starred__dataset__delete
      parameters:
      - name: dataset
        in: path
        required: true
        schema:
          type: string
          title: Dataset
      - name: PRIVATE-TOKEN
        in: header
        required: false
        schema:
          title: Private-Token
      - name: authorization
        in: header
        required: false
        schema:
          type: string
          title: Authorization
      responses:
        '204':
          description: Successful Response
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /vocabularies/countries:
    get:
      tags:
      - vocabularies
      summary: Get Countries
      description: All available countries.
      operationId: get_countries_vocabularies_countries_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Countries'
        '404':
          description: Not found
  /vocabularies/thematic-activities:
    get:
      tags:
      - vocabularies
      summary: Get Thematic Activities
      description: All available thematic activities.
      operationId: get_thematic_activities_vocabularies_thematic_activities_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThematicActivities'
        '404':
          description: Not found
  /vocabularies/affiliations:
    get:
      tags:
      - vocabularies
      summary: Get Affiliations
      description: All available affilitations.
      operationId: get_affiliations_vocabularies_affiliations_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Affiliations'
        '404':
          description: Not found
  /vocabularies/activity-sectors:
    get:
      tags:
      - vocabularies
      summary: Get Activity Sectors
      description: All available activity sectors.
      operationId: get_activity_sectors_vocabularies_activity_sectors_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ActivitySectors'
        '404':
          description: Not found
components:
  schemas:
    ActivitySectors:
      properties:
        activity_sectors:
          items:
            $ref: '#/components/schemas/VocabularyItem'
          type: array
          title: Activity Sectors
          default: []
      type: object
      title: ActivitySectors
      description: Activity sectors model.
    Affiliations:
      properties:
        affiliations:
          items:
            $ref: '#/components/schemas/VocabularyItem'
          type: array
          title: Affiliations
          default: []
      type: object
      title: Affiliations
      description: Affiliations model.
    Countries:
      properties:
        countries:
          items:
            $ref: '#/components/schemas/VocabularyItem'
          type: array
          title: Countries
          default: []
      type: object
      title: Countries
      description: Countries model.
    Dataset:
      properties:
        uid:
          type: string
          maxLength: 100
          minLength: 3
          title: Uid
      type: object
      required:
      - uid
      title: Dataset
      description: Dataset model.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Licence:
      properties:
        id:
          type: string
          title: Id
        revision:
          type: integer
          title: Revision
      type: object
      required:
      - id
      - revision
      title: Licence
      description: Licence model.
    LicenceData:
      properties:
        revision:
          type: integer
          title: Revision
      type: object
      required:
      - revision
      title: LicenceData
    LicenceFullData:
      properties:
        id:
          type: string
          title: Id
        revision:
          type: integer
          title: Revision
      type: object
      required:
      - id
      - revision
      title: LicenceFullData
    LicenceScopeCriterion:
      type: string
      enum:
      - all
      - dataset
      - portal
      title: LicenceScopeCriterion
    Licences:
      properties:
        licences:
          items:
            $ref: '#/components/schemas/Licence'
          type: array
          title: Licences
          default: []
      type: object
      title: Licences
      description: Licences model.
    LicencesData:
      properties:
        licences:
          items:
            $ref: '#/components/schemas/LicenceFullData'
          type: array
          title: Licences
      type: object
      required:
      - licences
      title: LicencesData
    MinimalUserInfo:
      properties:
        id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Id
        sub:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
      type: object
      title: MinimalUserInfo
      description: Minimal required info to recognize a user.
    RelatedData:
      properties:
        id:
          type: integer
          title: Id
        title:
          type: string
          title: Title
      type: object
      required:
      - id
      - title
      title: RelatedData
      description: Related data model.
    ThematicActivities:
      properties:
        thematic_activities:
          items:
            $ref: '#/components/schemas/VocabularyItem'
          type: array
          title: Thematic Activities
          default: []
      type: object
      title: ThematicActivities
      description: Thematic activities model.
    UserCreationData:
      properties:
        thematic_activity_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Thematic Activity Id
        affiliation_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Affiliation Id
        activity_sector_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Activity Sector Id
        country_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Country Id
        organisation:
          anyOf:
          - type: string
            maxLength: 128
            minLength: 1
          - type: 'null'
          title: Organisation
        contactable:
          type: boolean
          title: Contactable
          default: true
        licences:
          items:
            $ref: '#/components/schemas/LicenceFullData'
          type: array
          title: Licences
          default: []
      type: object
      title: UserCreationData
      description: Information set to create user record.
    UserData:
      properties:
        thematic_activity_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Thematic Activity Id
        affiliation_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Affiliation Id
        activity_sector_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Activity Sector Id
        country_id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Country Id
        organisation:
          anyOf:
          - type: string
            maxLength: 128
            minLength: 1
          - type: 'null'
          title: Organisation
        contactable:
          type: boolean
          title: Contactable
          default: true
      type: object
      title: UserData
      description: Information set to update user record.
    UserInfo:
      properties:
        id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Id
        sub:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub
        role:
          anyOf:
          - type: string
          - type: 'null'
          title: Role
        email:
          anyOf:
          - type: string
          - type: 'null'
          title: Email
        preferred_username:
          anyOf:
          - type: string
          - type: 'null'
          title: Preferred Username
        given_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Given Name
        family_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Family Name
        thematic_activity:
          anyOf:
          - $ref: '#/components/schemas/RelatedData'
          - type: 'null'
        affiliation:
          anyOf:
          - $ref: '#/components/schemas/RelatedData'
          - type: 'null'
        activity_sector:
          anyOf:
          - $ref: '#/components/schemas/RelatedData'
          - type: 'null'
        country:
          anyOf:
          - $ref: '#/components/schemas/RelatedData'
          - type: 'null'
        organisation:
          anyOf:
          - type: string
          - type: 'null'
          title: Organisation
        contactable:
          type: boolean
          title: Contactable
          default: true
        starred_datasets:
          items:
            type: string
          type: array
          title: Starred Datasets
          default: []
        tags:
          items:
            type: string
          type: array
          title: Tags
          default: []
        origin_portal:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Origin Portal
      type: object
      title: UserInfo
      description: Full set of user information handled by the service.
    UserPAT:
      properties:
        id:
          anyOf:
          - type: integer
          - type: 'null'
          title: Id
        sub:
          anyOf:
          - type: string
          - type: 'null'
          title: Sub
        pat:
          anyOf:
          - type: string
          - type: 'null'
          title: Pat
      type: object
      title: UserPAT
      description: Minimal required info to recognize a user + PAT.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    VocabularyItem:
      properties:
        id:
          type: integer
          title: Id
        label:
          type: string
          title: Label
      additionalProperties: true
      type: object
      required:
      - id
      - label
      title: VocabularyItem
      description: General vocabulary item model.
tags:
- name: account
  description: API to interact with user's account settings (user's data, authentication,
    permissions checks, etc.)
servers:
- url: https://cds.climate.copernicus.eu/api/profiles/v1
  description: Climate Data Store (absolute form of the published relative server)
- url: https://ads.atmosphere.copernicus.eu/api/profiles/v1
  description: Atmosphere Data Store
- url: https://ewds.climate.copernicus.eu/api/profiles/v1
  description: Early Warning Data Store
- url: /api/profiles/v1
x-source: https://cds.climate.copernicus.eu/api/profiles/v1/openapi.json
x-ownership: info.title names ECMWF Data Stores; ECMWF states at https://www.ecmwf.int/en/about/what-we-do/copernicus
  that it implements the Copernicus Climate Change Service (C3S) and Atmosphere Monitoring
  Service (CAMS), whose Data Stores run on *.copernicus.eu.
x-provenance:
  method: harvested
  publisher: ECMWF
  source: https://cds.climate.copernicus.eu/api/profiles/v1/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)