openapi: 3.1.0
info:
  title: Cockpit Global API
  description: |-
    Scaleway's Observability Cockpit allows you to monitor your applications and their infrastructure by giving you insights and context into their behavior. With Cockpit, you can visualize your resources' and applications' metrics, logs, and traces in Grafana dashboards. Cockpit is automatically activated when you are using [Scaleway resources that are integrated into it](https://www.scaleway.com/en/docs/cockpit/reference-content/cockpit-limitations/#product-integration-into-cockpit).

    The Global API allows you to perform Cockpit visualization actions such as retrieving your dashboard URLs, managing Grafana users, and synchronizing your data through Grafana dashboards. Refer to the [Cockpit API](https://www.scaleway.com/en/developers/api/cockpit/regional-api/) for data-related management.

    (switchcolumn)
    (switchcolumn)

    ## Concepts

    Refer to our [dedicated concepts page](https://www.scaleway.com/en/docs/observability/cockpit/concepts/) to find definitions of the different terms referring to Cockpit.

    (switchcolumn)
    (switchcolumn)
    ## Quickstart

    1. **Configure your environment variables.**

        <Message type="note">
        This is an optional step that seeks to simplify your usage of the API.
        </Message>

        ```bash
        export SCW_SECRET_KEY="<API secret key>"
        export SCW_PROJECT_ID="<Scaleway Project ID>"
        ```

    2. **Create a Grafana user with the `editor` role.**
        ```bash
        curl -X POST \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          -H "Content-Type: application/json" \
          -d '{"login":"user-name","role":"editor","project_id":"<Scaleway Project ID>"}' \
          "https://api.scaleway.com/cockpit/v1/grafana/users"
        ```
        <Message type="note">
        The `admin` username is not available for creation.
        </Message>
        **Your user's password displays in the output. Make sure that you store it securely.**

    3. **Retrieve a list of available dashboards in Grafana for all Scaleway resources integrated with Cockpit.**
        ```bash
        curl -X GET \
          -H "X-Auth-Token: $SCW_SECRET_KEY" \
          "https://api.scaleway.com/cockpit/v1/grafana/product-dashboards?project_id=<Scaleway Project ID>"
        ```
        The list of available dashboards displays in the output.
    (switchcolumn)
    <Message type="requirement">

     - You have a [Scaleway account](https://console.scaleway.com/)
     - You have [created an API key](https://www.scaleway.com/en/docs/iam/how-to/create-api-keys/) and that the API key has sufficient [IAM permissions](https://www.scaleway.com/en/docs/iam/reference-content/permission-sets/) to perform the actions described on this page
     - You have [installed `curl`](https://curl.se/download.html)
     - You have created [Scaleway resources integrated with Cockpit](https://www.scaleway.com/en/docs/cockpit/reference-content/cockpit-limitations/#product-integration-into-cockpit)
    </Message>
    (switchcolumn)


    ### Troubleshooting

    Refer to our troubleshooting documentation if [your pusher does not support HTTP headers](https://www.scaleway.com/en/docs/observability/cockpit/troubleshooting/pusher-does-not-support-custom-http-headers/) or if you want to [reset your Grafana password.](https://www.scaleway.com/en/docs/observability/cockpit/troubleshooting/resetting-grafana-password-via-the-api/)

    ## Technical limitations

    - It is not possible to create an `admin` Grafana user.
    - Available roles for Grafana users are `viewer` and `editor`.
    - The Scaleway preconfigured dashboards cannot be edited.


    ## Going further

    For more information about Cockpit, you can check out the following pages:

    - [Cockpit Documentation](https://www.scaleway.com/en/docs/observability/cockpit/)
    - [Scaleway Slack Community](http://slack.scaleway.com) join the #observability channel
    - [Contact our support team](https://console.scaleway.com/support/tickets).
  version: v1
servers:
- url: https://api.scaleway.com
tags:
- name: Grafana
  description: |
    Grafana is an open-source analytics and monitoring solution that is used to visualize data available in your Cockpit
    You need to create a Grafana user to access your Cockpit's Grafana. Note that the `admin` username is not available for creation.
    On Grafana you can also interact with the Scaleway alert manager and create alert rules.
- name: Pricing Plans (deprecated)
  description: |
    (Deprecated) A pricing plan is associated with each Cockpit. Pricing plans give you information on how you are billed for the Cockpit product.
components:
  schemas:
    scaleway.cockpit.v1.Grafana:
      type: object
      properties:
        grafana_url:
          type: string
          description: URL to access your Cockpit's Grafana.
      x-properties-order:
      - grafana_url
    scaleway.cockpit.v1.GrafanaProductDashboard:
      type: object
      properties:
        name:
          type: string
          description: Dashboard name.
        title:
          type: string
          description: Dashboard title.
        url:
          type: string
          description: Dashboard URL.
        tags:
          type: array
          description: Dashboard tags.
          items:
            type: string
        variables:
          type: array
          description: Dashboard variables.
          items:
            type: string
      x-properties-order:
      - name
      - title
      - url
      - tags
      - variables
    scaleway.cockpit.v1.GrafanaUser:
      type: object
      properties:
        id:
          type: integer
          description: ID of the Grafana user.
          format: uint32
        login:
          type: string
          description: Username of the Grafana user.
        role:
          type: string
          description: Role assigned to the Grafana user.
          enum:
          - unknown_role
          - editor
          - viewer
          x-enum-descriptions:
            values:
              unknown_role: Unknown role
              editor: Editor role
              viewer: Viewer role
          default: unknown_role
        password:
          type: string
          description: Grafana user's password.
          nullable: true
      x-properties-order:
      - id
      - login
      - role
      - password
    scaleway.cockpit.v1.ListGrafanaProductDashboardsResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total count of Grafana dashboards.
          format: uint64
        dashboards:
          type: array
          description: Grafana dashboards information.
          items:
            $ref: '#/components/schemas/scaleway.cockpit.v1.GrafanaProductDashboard'
      x-properties-order:
      - total_count
      - dashboards
    scaleway.cockpit.v1.ListGrafanaUsersResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total count of Grafana users.
          format: uint64
        grafana_users:
          type: array
          description: Grafana users information.
          items:
            $ref: '#/components/schemas/scaleway.cockpit.v1.GrafanaUser'
      x-properties-order:
      - total_count
      - grafana_users
    scaleway.cockpit.v1.ListPlansRequest.OrderBy:
      type: string
      enum:
      - name_asc
      - name_desc
      default: name_asc
    scaleway.cockpit.v1.ListPlansResponse:
      type: object
      properties:
        total_count:
          type: integer
          description: Total count of available pricing plans.
          format: uint64
        plans:
          type: array
          description: Plan types information.
          items:
            $ref: '#/components/schemas/scaleway.cockpit.v1.Plan'
      x-properties-order:
      - total_count
      - plans
    scaleway.cockpit.v1.Plan:
      type: object
      properties:
        name:
          type: string
          description: Name of a given pricing plan.
          enum:
          - unknown_name
          - free
          - premium
          - custom
          default: unknown_name
        retention_metrics_interval:
          type: string
          description: Interval of time during which Scaleway's Cockpit keeps your
            metrics. (in seconds)
          example: 2.5s
          nullable: true
        retention_logs_interval:
          type: string
          description: Interval of time during which Scaleway's Cockpit keeps your
            logs. (in seconds)
          example: 2.5s
          nullable: true
        retention_traces_interval:
          type: string
          description: Interval of time during which Scaleway's Cockpit keeps your
            traces. (in seconds)
          example: 2.5s
          nullable: true
        sample_ingestion_price:
          type: integer
          description: Ingestion price in cents for 1 million samples.
          format: uint32
        logs_ingestion_price:
          type: integer
          description: Ingestion price in cents for 1 GB of logs.
          format: uint32
        traces_ingestion_price:
          type: integer
          description: Ingestion price in cents for 1 GB of traces.
          format: uint32
        monthly_price:
          type: integer
          description: Retention price in euros per month.
          format: uint32
      x-properties-order:
      - name
      - retention_metrics_interval
      - retention_logs_interval
      - retention_traces_interval
      - sample_ingestion_price
      - logs_ingestion_price
      - traces_ingestion_price
      - monthly_price
  securitySchemes:
    scaleway:
      in: header
      name: X-Auth-Token
      type: apiKey
paths:
  /cockpit/v1/current-plan:
    get:
      tags:
      - Pricing Plans (deprecated)
      operationId: GetCurrentPlan
      summary: Get current plan
      description: |-
        Retrieve a pricing plan for the given Project, specified by the ID of the Project.
        Deprecated due to retention now being managed at the data source level.
      parameters:
      - in: query
        name: project_id
        description: ID of the Project. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.Plan'
      security:
      - scaleway: []
      deprecated: true
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/cockpit/v1/current-plan?project_id=6170692e-7363-616c-6577-61792e636f6d"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/cockpit/v1/current-plan" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id==6170692e-7363-616c-6577-61792e636f6d
  /cockpit/v1/grafana:
    get:
      tags:
      - Grafana
      operationId: GetGrafana
      summary: Get your Cockpit's Grafana
      description: |-
        Retrieve information on your Cockpit's Grafana, specified by the ID of the Project the Cockpit belongs to.
        The output returned displays the URL to access your Cockpit's Grafana.
      parameters:
      - in: query
        name: project_id
        description: ID of the Project. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.Grafana'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/cockpit/v1/grafana?project_id=6170692e-7363-616c-6577-61792e636f6d"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/cockpit/v1/grafana" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id==6170692e-7363-616c-6577-61792e636f6d
  /cockpit/v1/grafana/product-dashboards:
    get:
      tags:
      - Grafana
      operationId: ListGrafanaProductDashboards
      summary: List Scaleway resources dashboards
      description: Retrieve a list of available dashboards in Grafana, for all Scaleway
        resources which are integrated with Cockpit.
      parameters:
      - in: query
        name: project_id
        description: ID of the Project to target. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      - in: query
        name: page
        description: Page number.
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: Page size.
        schema:
          type: integer
          format: uint32
      - in: query
        name: tags
        description: Tags to filter for.
        schema:
          type: array
          items:
            type: string
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.ListGrafanaProductDashboardsResponse'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/cockpit/v1/grafana/product-dashboards?project_id=6170692e-7363-616c-6577-61792e636f6d"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/cockpit/v1/grafana/product-dashboards" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id==6170692e-7363-616c-6577-61792e636f6d
  /cockpit/v1/grafana/product-dashboards/{dashboard_name}:
    get:
      tags:
      - Grafana
      operationId: GetGrafanaProductDashboard
      summary: Get Scaleway resource dashboard
      description: Retrieve information about the dashboard of a Scaleway resource
        in Grafana, specified by the ID of the Project the Cockpit belongs to, and
        the name of the dashboard.
      parameters:
      - in: path
        name: dashboard_name
        description: Name of the dashboard.
        required: true
        schema:
          type: string
      - in: query
        name: project_id
        description: ID of the Project the dashboard belongs to. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.GrafanaProductDashboard'
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/cockpit/v1/grafana/product-dashboards/{dashboard_name}?project_id=6170692e-7363-616c-6577-61792e636f6d"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/cockpit/v1/grafana/product-dashboards/{dashboard_name}" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id==6170692e-7363-616c-6577-61792e636f6d
  /cockpit/v1/grafana/sync-data-sources:
    post:
      tags:
      - Grafana
      operationId: SyncGrafanaDataSources
      summary: Synchronize Grafana data sources
      description: Trigger the synchronization of all your data sources and the alert
        manager in the relevant regions. The alert manager will only be synchronized
        if you have enabled it.
      responses:
        "204":
          description: ""
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: ID of the Project to target. (UUID format)
                  example: 6170692e-7363-616c-6577-61792e636f6d
              x-properties-order:
              - project_id
      security:
      - scaleway: []
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X POST \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{"project_id":"6170692e-7363-616c-6577-61792e636f6d"}' \
            "https://api.scaleway.com/cockpit/v1/grafana/sync-data-sources"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/cockpit/v1/grafana/sync-data-sources" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id="6170692e-7363-616c-6577-61792e636f6d"
  /cockpit/v1/grafana/users:
    get:
      tags:
      - Grafana
      operationId: ListGrafanaUsers
      summary: (Deprecated) EOL 2026-01-20
      description: |-
        List Grafana users
        List all Grafana users created in your Cockpit's Grafana. By default, the Grafana users returned in the list are ordered in ascending order.
      parameters:
      - in: query
        name: page
        description: Page number.
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: Page size.
        schema:
          type: integer
          format: uint32
      - in: query
        name: order_by
        description: Order of the Grafana users.
        schema:
          type: string
          enum:
          - login_asc
          - login_desc
          default: login_asc
      - in: query
        name: project_id
        description: ID of the Project to target. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.ListGrafanaUsersResponse'
      security:
      - scaleway: []
      deprecated: true
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/cockpit/v1/grafana/users?project_id=6170692e-7363-616c-6577-61792e636f6d"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/cockpit/v1/grafana/users" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id==6170692e-7363-616c-6577-61792e636f6d
    post:
      tags:
      - Grafana
      operationId: CreateGrafanaUser
      summary: (Deprecated) EOL 2026-01-20
      description: |-
        Create a Grafana user
        Create a Grafana user to connect to your Cockpit's Grafana. Upon creation, your user password displays only once, so make sure that you save it.
        Each Grafana user is associated with a role: viewer or editor. A viewer can only view dashboards, whereas an editor can create and edit dashboards. Note that the `admin` username is not available for creation.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.GrafanaUser'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: ID of the Project in which to create the Grafana user.
                    (UUID format)
                  example: 6170692e-7363-616c-6577-61792e636f6d
                login:
                  type: string
                  description: Username of the Grafana user. Note that the `admin`
                    username is not available for creation.
                role:
                  type: string
                  description: Role assigned to the Grafana user.
                  enum:
                  - unknown_role
                  - editor
                  - viewer
                  x-enum-descriptions:
                    values:
                      unknown_role: Unknown role
                      editor: Editor role
                      viewer: Viewer role
                  default: unknown_role
              x-properties-order:
              - project_id
              - login
              - role
      security:
      - scaleway: []
      deprecated: true
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X POST \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{"login":"string","project_id":"6170692e-7363-616c-6577-61792e636f6d"}' \
            "https://api.scaleway.com/cockpit/v1/grafana/users"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/cockpit/v1/grafana/users" \
            X-Auth-Token:$SCW_SECRET_KEY \
            login="string" \
            project_id="6170692e-7363-616c-6577-61792e636f6d"
  /cockpit/v1/grafana/users/{grafana_user_id}:
    delete:
      tags:
      - Grafana
      operationId: DeleteGrafanaUser
      summary: (Deprecated) EOL 2026-01-20
      description: |-
        Delete a Grafana user
        Delete a Grafana user from your Cockpit's Grafana, specified by the ID of the Project the Cockpit belongs to, and the ID of the Grafana user.
      parameters:
      - in: path
        name: grafana_user_id
        description: ID of the Grafana user.
        required: true
        schema:
          type: integer
          format: uint32
      - in: query
        name: project_id
        description: ID of the Project to target. (UUID format)
        required: true
        schema:
          type: string
          example: 6170692e-7363-616c-6577-61792e636f6d
      responses:
        "204":
          description: ""
      security:
      - scaleway: []
      deprecated: true
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X DELETE \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/cockpit/v1/grafana/users/{grafana_user_id}?project_id=6170692e-7363-616c-6577-61792e636f6d"
      - lang: HTTPie
        source: |-
          http DELETE "https://api.scaleway.com/cockpit/v1/grafana/users/{grafana_user_id}" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id==6170692e-7363-616c-6577-61792e636f6d
  /cockpit/v1/grafana/users/{grafana_user_id}/reset-password:
    post:
      tags:
      - Grafana
      operationId: ResetGrafanaUserPassword
      summary: (Deprecated) EOL 2026-01-20
      description: |-
        Reset a Grafana user password
        Reset the password of a Grafana user, specified by the ID of the Project the Cockpit belongs to, and the ID of the Grafana user.
        A new password regenerates and only displays once. Make sure that you save it.
      parameters:
      - in: path
        name: grafana_user_id
        description: ID of the Grafana user.
        required: true
        schema:
          type: integer
          format: uint32
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.GrafanaUser'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: ID of the Project to target. (UUID format)
                  example: 6170692e-7363-616c-6577-61792e636f6d
              x-properties-order:
              - project_id
      security:
      - scaleway: []
      deprecated: true
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X POST \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{"project_id":"6170692e-7363-616c-6577-61792e636f6d"}' \
            "https://api.scaleway.com/cockpit/v1/grafana/users/{grafana_user_id}/reset-password"
      - lang: HTTPie
        source: |-
          http POST "https://api.scaleway.com/cockpit/v1/grafana/users/{grafana_user_id}/reset-password" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id="6170692e-7363-616c-6577-61792e636f6d"
  /cockpit/v1/plans:
    get:
      tags:
      - Pricing Plans (deprecated)
      operationId: ListPlans
      summary: List plan types
      description: |-
        Retrieve a list of available pricing plan types.
        Deprecated due to retention now being managed at the data source level.
      parameters:
      - in: query
        name: page
        description: Page number.
        schema:
          type: integer
          format: int32
      - in: query
        name: page_size
        description: Page size.
        schema:
          type: integer
          format: uint32
      - in: query
        name: order_by
        schema:
          $ref: '#/components/schemas/scaleway.cockpit.v1.ListPlansRequest.OrderBy'
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.ListPlansResponse'
      security:
      - scaleway: []
      deprecated: true
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X GET \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            "https://api.scaleway.com/cockpit/v1/plans"
      - lang: HTTPie
        source: |-
          http GET "https://api.scaleway.com/cockpit/v1/plans" \
            X-Auth-Token:$SCW_SECRET_KEY
    patch:
      tags:
      - Pricing Plans (deprecated)
      operationId: SelectPlan
      summary: Apply a pricing plan
      description: |-
        Apply a pricing plan on a given Project. You must specify the ID of the pricing plan type. Note that you will be billed for the plan you apply.
        Deprecated due to retention now being managed at the data source level.
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/scaleway.cockpit.v1.Plan'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                project_id:
                  type: string
                  description: ID of the Project. (UUID format)
                  example: 6170692e-7363-616c-6577-61792e636f6d
                plan_name:
                  type: string
                  description: Name of the pricing plan.
                  enum:
                  - unknown_name
                  - free
                  - premium
                  - custom
                  default: unknown_name
              x-properties-order:
              - project_id
              - plan_name
      security:
      - scaleway: []
      deprecated: true
      x-codeSamples:
      - lang: cURL
        source: |-
          curl -X PATCH \
            -H "X-Auth-Token: $SCW_SECRET_KEY" \
            -H "Content-Type: application/json" \
            -d '{"project_id":"6170692e-7363-616c-6577-61792e636f6d"}' \
            "https://api.scaleway.com/cockpit/v1/plans"
      - lang: HTTPie
        source: |-
          http PATCH "https://api.scaleway.com/cockpit/v1/plans" \
            X-Auth-Token:$SCW_SECRET_KEY \
            project_id="6170692e-7363-616c-6577-61792e636f6d"