openapi: 3.0.0
info:
  description: Description of Pryv.io API in Open API 3.0 standard format
  version: 2.0.0-pre
  title: Pryv.io API
  contact:
    email: support@pryv.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
paths:
  /auth/login:
    post:
      description: >-
        Authenticates the user against the provided credentials, opening a
        personal access session. By default, the session is valid for 14 days
        after the last token usage. This duration is configurable in the
        platform parameters.

        This is one of the only API methods that do not expect an [auth parameter](#basics-authorization).

        This method requires that the `appId` and `Origin` (or `Referer`) header comply with the [trusted app verification](#basics-trusted-apps-verification).
      operationId: auth.login
      parameters:
        - in: header
          name: Origin
          schema:
            type: string
            format: uri
          required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: string
                - type: string
                - type: string
                - $ref: "#/components/schemas/timestamp"
                - $ref: "#/components/schemas/timestamp"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                username:
                  description: The user's username.
                  type: string
                password:
                  description: The user's password.
                  type: string
                appId:
                  description: Your app's unique identifier.
                  type: string
  /auth/logout:
    post:
      description: >-
        Terminates a personal access session by invalidating its access
        token (the user will have to login again).

        Simply provide the Authorization token in own of [the supported ways](/reference/#authorization), no request body is required.
      operationId: auth.logout
      responses:
        "200": {}
  /mfa/activate:
    post:
      description: >-
        Initiates the MFA activation flow for a given Pryv.io user,
        triggering the MFA challenge.


        Requires a personal token as [authorization](#basics-authorization), which should be obtained during a prior [Login call](#methods-auth-auth-login).
      operationId: mfa.activate
      responses:
        "302":
          content:
            application/json:
              schema:
                - type: string
      requestBody:
        description: The parameters depend entirely on the chosen MFA method and will be
          forwarded as-is to the service generating the challenge. Make sure to
          URL encode parameters if they appear in query parameters.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/false"
  /mfa/confirm:
    post:
      description: >-
        Confirms the MFA activation by verifying the MFA challenge
        triggered by a prior [MFA activation call](#methods-mfa-mfa-activate).


        Requires a MFA session token as [authorization](#basics-authorization).
      operationId: mfa.confirm
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: array
                  items: strings
        "403":
          description: forbidden
      requestBody:
        description: The parameters depend entirely on the chosen MFA method and will be
          forwarded to the service verifying the challenge.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/false"
  /mfa/challenge:
    post:
      description: >-
        Triggers the MFA challenge, depending on the chosen MFA method
        (e.g. send a verification code by SMS).


        Requires a MFA session token as [authorization](#basics-authorization).
      operationId: mfa.challenge
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: string
        "403":
          description: forbidden
  /mfa/verify:
    post:
      description: >-
        Verifies the MFA challenge triggered by a prior [MFA challenge
        call](#methods-mfa-mfa-challenge).


        Requires a MFA session token as [authorization](#basics-authorization).
      operationId: mfa.verify
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: string
        "403":
          description: forbidden
      requestBody:
        description: The parameters depend entirely on the chosen MFA method and will be
          forwarded to the service verifying the challenge.
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/false"
  /mfa/deactivate:
    post:
      description: |-
        Deactivate MFA for a given Pryv.io user.

        Requires a personal token as [authorization](#basics-authorization).
      operationId: mfa.deactivate
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: string
  /mfa/recover:
    post:
      description: >-
        Deactivate MFA for a given Pryv.io user using a MFA recovery code.


        This is useful when [Deactivate MFA](#methods-mfa-mfa-deactivate) can not be used (in case of 2nd factor loss).

        Instead, requires a MFA recovery code (obtained when [confirming the MFA activation](#methods-mfa-mfa-confirm)), as well as the usual [Login](#methods-auth-auth-login) parameters.
      operationId: mfa.recover
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: string
        "400":
          description: invalid-parameter
      requestBody:
        description: Similar to the usual [Login](#methods-auth-auth-login) parameters,
          as well as
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/false"
  /:
    post:
      description: Sends a batch of API methods calls in one go (e.g. for syncing
        offline changes when resuming connectivity).
      operationId: callBatch
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: array
                  items: call results
      requestBody:
        description: Array of method call objects, each defined as follows
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/false"
  /events:
    get:
      description: Queries accessible events.
      operationId: events.get
      parameters:
        - name: fromTime
          description: The start time of the timeframe you want to retrieve events for.
            Default is 24 hours before `toTime` if the latter is set; otherwise
            it is not taken into account.
          required: false
          in: query
        - name: toTime
          description: "The end time of the timeframe you want to retrieve events for.
            Default is the current time if `fromTime` is set. We recommend to
            set both `fromTime` and `toTime` (for example by choosing a very
            small number for `fromTime` or a large one for `toTime` if you want
            to retrieve all events). Note: events are considered to be within a
            given timeframe based on their `time` and `duration`."
          required: false
          in: query
        - name: streams
          description: >-
            
            **Array of streamIds:** Events assigned to any of the specified streams or their children will be returned.


            or


            **[Streams query](#data-structure-streams-query)**: Object used for filtering events by complex streamIds relations.


            By default, all accessible events are returned regardless of their stream.
          required: false
          in: query
        - name: tags
          description: >-
            **(DEPRECATED)** Please use [streams
            query](#data-structure-streams-query) instead.


            If set, only events assigned to any of the listed tags will be returned.
          required: false
          in: query
        - name: types
          description: If set, only events of any of the listed types will be returned.
          required: false
          in: query
        - name: content
          description: If set, only events whose `content` matches all the conditions will
            be returned. See [content query](#data-structure-content-query) for
            the condition syntax, supported operators and availability. Server
            support is advertised by `features.contentQueries` in [service
            info](#service-info).
          required: false
          in: query
        - name: clientData
          description: Same as `content`, applied to the events' `clientData`. Conditions
            from both parameters must all match.
          required: false
          in: query
        - name: running
          description: If `true`, only running period events will be returned.
          required: false
          in: query
        - name: sortAscending
          description: "If `true`, events will be sorted from oldest to newest. Default:
            false (sort descending)."
          required: false
          in: query
        - name: skip
          description: The number of items to skip in the results.
          required: false
          in: query
        - name: limit
          description: The number of items to return in the results. A default value of 20
            items is used if no other range limiting parameter is specified
            (`fromTime`, `toTime`).
          required: false
          in: query
        - name: state
          description: Indicates what items to return depending on their state. By
            default, only items that are not in the trash are returned;
            `trashed` returns only items in the trash, while `all` return all
            items regardless of their state.
          required: false
          in: query
        - name: modifiedSince
          description: If specified, only events modified since that time will be returned.
          required: false
          in: query
        - name: includeDeletions
          description: Whether to include event deletions since `modifiedSince` for sync
            purposes (only applies when `modifiedSince` is set). Defaults to
            `false`.
          required: false
          in: query
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: array
                  items: "[events](#data-structure-event)"
                - type: array
                  items: "[item deletions](#data-structure-item-deletion)"
    post:
      description: Records a new event, in addition to JSON, this request accepts
        standard multipart/form-data content to support the creation of event
        with attached files in a single request. When sending a multipart
        request, one content part must hold the JSON for the new event and all
        other content parts must be the attached files.
      operationId: events.create
      responses:
        "201":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/event"
        "400":
          description: invalid-operation
      requestBody:
        description: The new event's data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/event"
  "/events/{id}":
    get:
      description: Fetches a specific event. This request is mostly used to fetch an
        event's version history, allowing to review all the modifications to an
        event's data.
      operationId: events.getOne
      parameters:
        - name: includeHistory
          description: "If `true`, the event's history will be added to the response.
            Default: false (don't include the history)."
          required: false
          in: query
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/event"
                - type: array
                  items: "[events](#data-structure-event)"
    put:
      description: Modifies the event.
      operationId: events.update
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/event"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
    post:
      description: Adds one or more file attachments to the event. This request
        expects standard multipart/form-data content, with all content parts
        being the attached files.
      operationId: events.addAttachment
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/event"
    delete:
      description: >-
        Trashes or deletes the specified event, depending on its current
        state:


        - If the event is not already in the trash, it will be moved to the trash (i.e. flagged as `trashed`)

        - If the event is already in the trash, it will be irreversibly deleted (including all its attached files, if any).
      operationId: events.delete
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/item-deletion"
  "/events/{id}/{fileId}[/{fileName}]":
    get:
      description: >-
        Gets the attached file. Accepts an arbitrary filename path suffix
        (ignored) for easier link readability.

        For this function using the `auth` query parameter is not accepted. You can either use the [access token](#data-structure-access) in the `Authorization` header or provide the `readToken` as query parameter.
      operationId: events.getAttachment
      parameters:
        - name: readToken
          description: Required if not using the `Authorization` HTTP header. The file
            read token to authentify the request. See
            [`event.attachments[].readToken`](#data-structure-event) for more
            info.
          required: true
          in: query
        - name: id
        - name: fileId
        - name: fileName
      responses:
        "200":
          description: OK
  "/events/{id}/{fileId}":
    delete:
      description: Irreversibly deletes the attached file.
      operationId: events.deleteAttachment
      parameters:
        - name: fileId
          description: The id of the attached file.
          required: true
          in: query
        - name: id
        - name: fileId
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/event"
  "/events/{id}/series":
    get:
      description: >-
        Retrieves HF series data points from a HF event.

        Returns data in order of ascending deltaTime between "fromTime" and "toTime".

        Data is returned as input, no sampling or aggregation is performed.
      operationId: hfs.get
      parameters:
        - name: fromDeltaTime
          description: Only returns data points later than this deltaTime. If no value is
            given the query will return data starting at the earliest deltaTime
            in the series.
          required: false
          in: query
        - name: toDeltaTime
          description: Only returns data points earlier than this deltaTime. If no value
            is given the server will return only data that is in the past.
          required: false
          in: query
        - name: id
      responses:
        "200":
          description: OK
    post:
      description: >-
        Adds new HF series data points to a HF event.


        The HF series data will only store one set of values for any given deltaTime. This means you can update existing data points by 'adding' new data with the original deltaTime.
      operationId: hfs.add
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: string
        "400":
          description: invalid-operation
      requestBody:
        description: The new HF series data point(s), see [HF
          series](#data-structure-high-frequency-series).
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/high-frequency-series"
  /series/batch:
    post:
      description: >-
        Adds data to multiple HF series (stored in multiple HF events) in a
        single atomic operation. This is the fastest way to append data to Pryv;
        it allows transferring many data points in a single request.


        For this operation to be successful, all of the following conditions must be fulfilled:

          - The access token needs write permissions to all series identified by "eventId".
          - All events referred to must be HF events (type starts with the string "series:").
          - Fields identified in each individual message must match those specified by the type of the HF event; there must be no duplicates.
          - All the values in every data point must conform to the type specification.

        If any part of the batch message is invalid, the entire batch is aborted and the returned result body identifies the error.
      operationId: hfs.addBatch
      responses:
        "201":
          content:
            application/json:
              schema:
                - type: string
        "400":
          description: invalid-request-structure
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                format:
                  description: The format string "seriesBatch".
                  type: string
                data:
                  description: "Array of batch entries. Each batch entry is defined as follows:"
                  type: array
  /streams:
    get:
      description: Gets the accessible streams hierarchy.
      operationId: streams.get
      parameters:
        - name: parentId
          description: "The id of the parent stream from which to retrieve streams.
            Default: `null` (returns all accessible streams from the root
            level)."
          required: false
          in: query
        - name: state
          description: By default, only items that are not in the trash are returned;
            `all` return all items regardless of their state.
          required: false
          in: query
        - name: includeDeletionsSince
          description: Whether to include stream deletions since that time for sync
            purposes.
          required: false
          in: query
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: array
                  items: "[streams](#data-structure-stream)"
                - type: array
                  items: "[item deletions](#data-structure-item-deletion)"
    post:
      description: Creates a new stream.
      operationId: streams.create
      responses:
        "201":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/stream"
        "400":
          description: invalid-item-id
        "409":
          description: item-already-exists
      requestBody:
        description: The new stream's data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/stream"
  "/streams/{id}":
    put:
      description: Modifies the stream.
      operationId: streams.update
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/stream"
        "409":
          description: item-already-exists
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
    delete:
      description: >-
        Trashes or deletes the specified stream, depending on its current
        state:


        - If the stream is not already in the trash, it will be moved to the trash (i.e. flagged as `trashed`)

        - If the stream is already in the trash, it will be irreversibly deleted with its descendants (if any). If events exist that refer to the deleted item(s), you must indicate how to handle them with the parameter `mergeEventsWithParent`.
      operationId: streams.delete
      parameters:
        - name: mergeEventsWithParent
          description: Required if actually deleting the item and if it (or any of its
            descendants) has linked events, ignored otherwise. If `true`, the
            linked events will be assigned to the parent of the deleted item; if
            `false`, the linked events will be deleted.
          required: true
          in: query
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/item-deletion"
  /accesses:
    get:
      description: >-
        Gets accesses that were created by your access token, unless you're
        using a personal token then it returns all accesses.

        Only returns accesses that are active when making the request. To include accesses that have expired or were deleted, use

        the `includeExpired` or `includeDeletions` parameters respectively.


        In v2 the returned `id`, `createdBy`, and `modifiedBy` fields use the composite reference format `<base>:<serial>` for accesses that have been updated at least once. Never-updated accesses still serialise as bare cuid (`<base>`) for full backwards-compatibility. Parse with `pryv.utils.parseAccessRef(ref)` if you need to extract the version.
      operationId: accesses.get
      parameters:
        - name: includeExpired
          description: If `true`, also includes expired accesses. Defaults to `false`.
          required: false
          in: query
        - name: includeDeletions
          description: If `true`, also includes deleted accesses. Defaults to `false`.
          required: false
          in: query
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: array
                  items: "[accesses](#data-structure-access)"
                - type: array
                  items: deleted [accesses](#data-structure-access)
    post:
      description: >-
        Creates a new access. You can only create accesses whose
        permissions are a subset of those granted to your own access token.


        **v2 behaviour change** (Pryv.io ≥ 2.0.0-pre.X): when an `app` access creates a `shared` access scoped under it, the new shared's `expires` (resolved from `expireAfter` if provided) cannot exceed the managing app's `expires`. Violations return `invalid-operation` with `data: { parentExpires, requestedExpires }`. Personal-issued accesses are not subject to this check (personal accesses typically have no `expires`).
      operationId: accesses.create
      responses:
        "201":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/access"
        "400":
          description: invalid-item-id
      requestBody:
        description: An object with the new access's data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/access"
  "/accesses/{id}":
    get:
      description: >-
        Returns the access identified by `{id}`. The id can be either:


        - **bare** `<base>` — returns the current head row.

        - **composite** `<base>:<serial>` matching the current head's serial — returns the current head row.

        - **composite** `<base>:<serial>` referring to an *older* serial — returns the historical snapshot from that version, alongside a `current` hint pointing at the live head's composite id. Mirrors GitHub's `GET /repos/X/Y/commits/<sha>` behaviour for ref-by-version.

        - any other id (unknown base, or a serial that never existed) — `404 unknown-resource`.


        Pass `?includeHistory=true` to also return the full chronological history of the access (oldest first) in a `history` array. Default `false` — the singular case covers the typical "audit this access" use case without the list-side overhead.


        App callers can only fetch their own access (self) or shared accesses they directly manage; other access ids return `404 unknown-resource` to avoid info leakage.
      operationId: accesses.getOne
      parameters:
        - name: includeHistory
          description: If `true`, include the chronological history of the access.
            Defaults to `false`.
          required: false
          in: query
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/access"
                - type: string
                - type: array
                  items: "[accesses](#data-structure-access)"
        "404":
          description: unknown-resource
    put:
      description: >-
        Updates the access identified by `{id}`. Each successful update
        mutates the head row, snapshots the prior state into history, and bumps
        the access's `serial`. The returned access carries the new wire-format
        composite id `<base>:<serial>` (or bare `<base>` when never updated).


        **Mutable fields** (whitelist): `name`, `deviceName`, `permissions`, `expireAfter` / `expires`, `clientData`. Anything else returns `invalid-parameters-format`.


        **Caller-vs-target matrix**:

        - `personal` accesses are immutable (no caller can update them).

        - An `app` access can update only the `shared` accesses it directly manages.

        - `shared` accesses cannot update anything.

        - No self-update via this method (self-revoke stays available via `accesses.delete`).


        **Chain rules enforced on update**:

        - A managed `shared`'s new `permissions` must remain a subset of its managing `app`'s permissions.

        - Narrowing an `app`'s permissions (or `expires`) is strict-rejected if any managed `shared` would now sit outside the new scope or outlive the new expiry. The error includes `data.offendingChildren: [ids]` so the caller can resolve children first and retry.

        - A managed `shared`'s `expires` cannot exceed its managing `app`'s `expires` (parent with `expires: null` imposes no cap).


        **Composite-id conflict**: the `{id}` must match the current head's `serial`. A stale composite returns `409 stale-resource` with `data: { provided, currentSerial }`; refetch the access via [Get one access](#methods-accesses-accesses-getOne) and retry with the current head id. Bare `<base>` is only valid on a never-updated access.


        On success, the server emits an `accessesChanged` socket.io event (coarse-grained) and an `accessUpdated` event with payload `{ type: 'access-updated', accessId, serial }` (fine-grained).
      operationId: accesses.update
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/access"
        "400":
          description: invalid-operation
        "403":
          description: forbidden
        "404":
          description: unknown-resource
        "409":
          description: stale-resource
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
    delete:
      description: >-
        Deletes the specified access. Personal accesses can delete any
        access. App accesses can delete shared accesses they created. Deleting
        an app access deletes the shared ones it created.

        All accesses can also perform a self-delete unless a forbidden `selfRevoke` permission has been set.


        **v2 behaviour change** (Pryv.io ≥ 2.0.0-pre.X): the `{id}` is composite-aware — pass the composite `<base>:<serial>` you last observed via [Get accesses](#methods-accesses-accesses-get) or [Get one access](#methods-accesses-accesses-getOne). A stale composite returns `409 stale-resource` with `data: { provided, currentSerial }`; refetch and retry. Bare `<base>` is only valid on a never-updated access.
      operationId: accesses.delete
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/item-deletion"
                - type: array
                  items: "[item deletions](#data-structure-item-deletion)"
  /accesses/check-app:
    post:
      description: For the app authorization process. Checks if the app requesting
        authorization already has access with the same permissions (and on the
        same device, if applicable), and returns details of the requested
        permissions' streams (for display) if not.
      operationId: accesses.checkApp
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: array
                  items: permission request objects
                - $ref: "#/components/schemas/access"
                - $ref: "#/components/schemas/access"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                requestingAppId:
                  description: The id of the app requesting authorization.
                  type: string
                deviceName:
                  description: The name of the device running the app requesting authorization, if
                    applicable.
                  type: string
                requestedPermissions:
                  description: An array of permission request objects, which are identical to
                    stream permission objects of
                    [accesses](#data-structure-access) except that each stream
                    permission object must have a `defaultName` property
                    specifying the name the stream should be created with later
                    if missing.
                  type: array of permission request objects
  /access-info:
    get:
      description: Retrieves information about the access in use.
      operationId: getAccessInfo
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                - type: "[key-value](#methods-key-value-)"
                - type: "[key-value](#methods-key-value-)"
  /webhooks:
    get:
      description: Gets manageable webhooks. Only returns webhooks that were created
        by the access, unless you are using a personal access which returns all
        existing webhooks in the user's account.
      operationId: webhooks.get
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: array
                  items: "[webhooks](#data-structure-webhook)"
    post:
      description: Creates a new webhook. You can only create webhooks with `app` and
        `shared` accesses.
      operationId: webhooks.create
      responses:
        "201":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/webhook"
      requestBody:
        description: An object with the new webhook's data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/webhook"
  "/webhooks/{id}":
    get:
      description: Fetches a specific webhook. Only returns a webhook if it was
        created by the access, unless you are using a personal access which is
        allowed to fetch any existing webhook in the user's account.
      operationId: webhooks.getOne
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/webhook"
    put:
      description: >-
        Modifies the webhook. You can only modify webhooks with the access
        that was used to create them, unless you are using a personal token.

        Updating the `state` to `active` resets the `currentRetries` counter.
      operationId: webhooks.update
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/webhook"
        "409":
          description: item-already-exists
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
    delete:
      description: Deletes the specified webhook. You can only delete webhooks with
        the access that was used to create them, unless you are using a personal
        token.
      operationId: webhooks.delete
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/item-deletion"
  "/webhooks/{id}/test":
    post:
      description: Sends a post request containing a message called `test` to the URL
        of the specified webhook's `url`. You can only test webhooks with the
        access that was used to create them, unless you are using a personal
        token.
      operationId: webhooks.test
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/webhook"
        "400":
          description: unknown-referenced-resource
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /followed-slices:
    get:
      description: Gets followed slices.
      operationId: followedSlices.get
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: array
                  items: "[followed slices](#data-structure-followed-slice)"
    post:
      description: Creates a new followed slice.
      operationId: followedSlices.create
      responses:
        "201":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/followed-slice"
      requestBody:
        description: An object with the new followed slice's data
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/followed-slice"
  "/followed-slices/{id}":
    put:
      description: Modifies the specified followed slice.
      operationId: followedSlices.update
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/followed-slice"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
    delete:
      description: Deletes the specified followed slice.
      operationId: followedSlices.delete
      parameters:
        - name: id
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/item-deletion"
  /profile/app:
    get:
      description: Gets the app's dedicated profile set, which contains app-level
        settings for the user. Available to app accesses.
      operationId: profile.getApp
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: object
    put:
      description: |-
        Adds, updates or delete app profile keys. Available to app accesses.

        - To add or update a key, just set its value
        - To delete a key, set its value to `null`

        Existing keys not included in the update are left untouched.
      operationId: profile.updateApp
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: object
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /profile/public:
    get:
      description: Gets the public profile set, which contains the information the
        user makes publicly available (e.g. avatar image). Available to all
        accesses.
      operationId: profile.getPublic
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: object
    put:
      description: >-
        Adds, updates or delete public profile keys. Available to personal
        accesses.


        - To add or update a key, just set its value

        - To delete a key, set its value to `null`


        Existing keys not included in the update are left untouched.
      operationId: profile.updatePublic
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: object
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /profile/private:
    get:
      description: Gets the private profile set. Available to personal accesses.
      operationId: profile.getPrivate
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: object
    put:
      description: >-
        Adds, updates or delete private profile keys. Available to personal
        accesses.


        - To add or update a key, just set its value

        - To delete a key, set its value to `null`


        Existing keys not included in the update are left untouched.
      operationId: profile.updatePrivate
      responses:
        "200":
          content:
            application/json:
              schema:
                - type: object
  /account:
    get:
      description: |-
        **(DEPRECATED)** Please use events methods instead.

        Retrieves the user's account information.
      operationId: account.get
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/account"
    put:
      description: |-
        **(DEPRECATED)** Please use events methods instead.

        Modifies the user's account information.
      operationId: account.update
      responses:
        "200":
          content:
            application/json:
              schema:
                - $ref: "#/components/schemas/account"
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties: {}
  /account/change-password:
    post:
      description: >-
        Modifies the user's password.

        Enforces password complexity, reuse and minimum age rules if enabled (set via the corresponding platform settings).
      operationId: account.changePassword
      responses:
        "200": {}
        "400":
          description: invalid-parameters-format
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                oldPassword:
                  description: The current password.
                  type: string
                newPassword:
                  description: The new password.
                  type: string
  /account/request-password-reset:
    post:
      description: >-
        Requests the resetting of the user's password. An e-mail containing
        an expiring reset token (e.g. in a link) will be sent to the user.

        This method requires that the `appId` and `Origin` (or `Referer`) header comply with the [trusted app verification](#basics-trusted-apps-verification).
      operationId: account.requestPasswordReset
      responses:
        "200": {}
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                appId:
                  description: Your app's unique identifier.
                  type: string
  /account/reset-password:
    post:
      description: >-
        Resets the user's password, authorizing the request with the given
        reset token (see [request password
        reset](#methods-account-account-requestPasswordReset) ).

        Enforces password complexity, reuse and minimum age rules if enabled (set via the corresponding platform settings).

        This method requires that the `appId` and `Origin` (or `Referer`) header comply with the [trusted app verification](#basics-trusted-apps-verification).
      operationId: account.resetPassword
      responses:
        "200": {}
        "400":
          description: invalid-parameters-format
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                resetToken:
                  description: The expiring reset token that was sent to the user after requesting
                    the password reset.
                  type: string
                newPassword:
                  description: The new password.
                  type: string
                appId:
                  description: Your app's unique identifier.
                  type: string
components:
  schemas:
    event:
      type: object
      properties:
        id:
          uniqueItems: true
          readOnly: (except at creation)
          required: true
          description: The identifier ([collision-resistant cuid](https://usecuid.org/))
            for the event. Automatically generated if not set when creating the
            event.
          $ref: "#/components/schemas/identifier"
        streamIds:
          required: true
          description: The ids of the belonging streams.
          type: array
          items:
            type:
              $ref: "#/components/schemas/identifier"
        streamId:
          required: true
          description: |-
            **(DEPRECATED)** Please use streamIds instead.

            The id of the first element of the streamIds array.
          $ref: "#/components/schemas/identifier"
        time:
          required: true
          description: The event's time. For period events, this is the time the event
            started. Automatically set to the server time if not provided when
            creating the event.
          $ref: "#/components/schemas/timestamp"
        duration:
          description: If present and non-zero, indicates that the event is a period
            event. **Running period events have a duration set to `null`**. **A
            duration set to zero is equivalent to no duration**.
          $ref: "#/components/schemas/timestamp"
        type:
          required: true
          description: The type of the event. See the [event type
            directory](/event-types/#directory) for a list of standard types.
          type: string
        content:
          description: The `type`-specific content of the event, if any.
          type: any type
        tags:
          description: |-
            **(DEPRECATED)** Please use streamIds instead.

            The tags associated with the event.
          type: array
          items:
            type: strings
        description:
          description: User description or comment for the event.
          type: string
        attachments:
          readOnly: true
          description: "An array describing the files attached to the event. Each item has
            the following structure:"
          type: array
          items:
            type: attachment objects
        clientData:
          description: Additional client data for the event.
          $ref: "#/components/schemas/key-value"
        trashed:
          description: "`true` if the event is in the trash."
          type: boolean
        integrity:
          readOnly: true
          description: Integrity check for event object.
          $ref: "#/components/schemas/integrity"
        created:
          readOnly: true
          required: true
          description: The time the event was created.
          $ref: "#/components/schemas/timestamp"
        createdBy:
          readOnly: true
          required: true
          description: The id of the access used to create the event.
          $ref: "#/components/schemas/identifier"
        modified:
          readOnly: true
          required: true
          description: The time the event was last modified.
          $ref: "#/components/schemas/timestamp"
        modifiedBy:
          readOnly: true
          required: true
          description: The id of the last access used to modify the event.
          $ref: "#/components/schemas/identifier"
    stream:
      type: object
      properties:
        id:
          uniqueItems: true
          readOnly: (except at creation)
          required: true
          description: The identifier for the stream. Automatically generated if not set
            when creating the stream; **slugified if necessary**.
          $ref: "#/components/schemas/identifier"
        name:
          uniqueItems: among siblings
          required: true
          description: A name identifying the stream for users. The name must be unique
            among the stream's siblings in the streams tree structure.
          type: string
        parentId:
          description: The identifier of the stream's parent, if any. A value of `null`
            indicates that the stream has no parent (i.e. root stream).
          $ref: "#/components/schemas/identifier"
        clientData:
          description: Additional client data for the stream.
          $ref: "#/components/schemas/key-value"
        children:
          readOnly: true
          required: true
          description: "The stream's sub-streams, if any. This field cannot be set in
            requests creating a new streams: streams are created individually by
            design."
          type: array
          items:
            type: streams
        trashed:
          description: "`true` if the stream is in the trash."
          type: boolean
        created:
          readOnly: true
          required: true
          description: The time the stream was created.
          $ref: "#/components/schemas/timestamp"
        createdBy:
          readOnly: true
          required: true
          description: The id of the access used to create the stream.
          $ref: "#/components/schemas/identifier"
        modified:
          readOnly: true
          required: true
          description: The time the stream was last modified.
          $ref: "#/components/schemas/timestamp"
        modifiedBy:
          readOnly: true
          required: true
          description: The id of the last access used to modify the stream.
          $ref: "#/components/schemas/identifier"
    access:
      type: object
      properties:
        id:
          uniqueItems: true
          readOnly: true
          required: true
          description: The identifier for the access.
          $ref: "#/components/schemas/identifier"
        token:
          uniqueItems: true
          readOnly: (except at creation)
          required: true
          description: The token identifying the access. Automatically generated if not
            set when creating the access; **slugified if necessary**.
          type: string
        apiEndpoint:
          readOnly: true
          required: true
          description: The API endpoint with the access' authorization token. See [app
            guidelines](/guides/app-guidelines/).
          type: string
        type:
          readOnly: (except at creation)
          description: "The type — or usage — of the access. Default: `shared`."
          schema:
            type: string
            enum:
              - personal
              - app
              - shared
        name:
          uniqueItems: per type and device
          readOnly: (except at creation)
          required: true
          description: The name identifying the access for the user. (For personal and app
            access, the name is used as a technical identifier and not shown
            as-is to the user.)
          type: string
        deviceName:
          uniqueItems: per type and name
          readOnly: (except at creation)
          description: For app accesses only. The name of the client device running the
            app, if applicable.
          type: string
        permissions:
          readOnly: (except at creation)
          required: true
          description: 'Ignored for personal accesses. If permission levels conflict (e.g.
            stream set to "manage" and child stream set to "contribute"), the
            child stream level applies. Each permission object has the following
            structure:'
          type: array
          items:
            type: permission objects
        lastUsed:
          readOnly: true
          description: The time the access was last used.
          $ref: "#/components/schemas/timestamp"
        expireAfter:
          readOnly: (except at creation)
          description: >-
            If set, controls access expiry in seconds.

            When given a number in this attribute (positive or zero), the access will expire (and not be usable anymore) after this many seconds.
          type: number
        expires:
          readOnly: true
          description: >-
            If the access was set to expire: The timestamp after which the
            access

            will be deactivated.
          $ref: "#/components/schemas/timestamp"
        deleted:
          readOnly: true
          description: "If the access has been deleted: The timestamp of the deletion."
          $ref: "#/components/schemas/timestamp"
        clientData:
          readOnly: (except at creation)
          description: Additional client data for the access.
          $ref: "#/components/schemas/key-value"
        integrity:
          readOnly: true
          description: Integrity check for access object.
          $ref: "#/components/schemas/integrity"
        created:
          readOnly: true
          required: true
          description: The time the access was created.
          $ref: "#/components/schemas/timestamp"
        createdBy:
          readOnly: true
          required: true
          description: The id of the access used to create the access.
          $ref: "#/components/schemas/identifier"
        modified:
          readOnly: true
          required: true
          description: The time the access was last modified.
          $ref: "#/components/schemas/timestamp"
        modifiedBy:
          readOnly: true
          required: true
          description: The id of the last access used to modify the access.
          $ref: "#/components/schemas/identifier"
    followed-slice:
      type: object
      properties:
        id:
          uniqueItems: true
          readOnly: true
          required: true
          description: The server-assigned identifier for the followed slice.
          $ref: "#/components/schemas/identifier"
        name:
          uniqueItems: true
          required: true
          description: A name identifying the followed slice for the user.
          type: string
        url:
          required: true
          description: The URL of the API endpoint of the account hosting the slice. Not
            modifiable after creation.
          type: URL
        accessToken:
          required: true
          description: The token of the shared access itself. Not modifiable after creation.
          type: string
    account:
      type: object
      properties:
        username:
          uniqueItems: true
          readOnly: true
          required: true
          description: The user's username.
          type: string
        email:
          uniqueItems: true
          required: true
          description: The user's contact e-mail address.
          type: string
        language:
          required: true
          description: The user's preferred language as a 2-letter ISO language code.
          type: string
        storageUsed:
          required: true
          description: The current storage size used by the user account.
          type: object
    high-frequency-series:
      type: object
      properties:
        format:
          required: true
          description: The data format (for now only "flatJSON" format is supported).
          type: string
        fields:
          required: true
          description: >-
            The "fields" array lists all the fields that you will be providing
            in the "points" array, including the "deltaTime" field in first
            position.

            If the data type contains a single field (ex.: mass/kg), the second field is "value", otherwise, it is the list of fields with the required ones first.
          type: Array of fields
        points:
          required: true
          description: >-
            The "points" array contains the data points, each data point is
            represented by a simple array.

            This makes the bulk of the message (your data points) very space-efficient; values are encoded positionally.

            The first value corresponds to the first field, and so on.
          type: Array of data points
    webhook:
      type: object
      properties:
        id:
          readOnly: true
          required: true
          description: The identifier of the Webhook.
          $ref: "#/components/schemas/identifier"
        accessId:
          readOnly: true
          required: true
          description: The identifier of the access that was used to create the Webhook.
          $ref: "#/components/schemas/identifier"
        url:
          uniqueItems: per app access
          readOnly: (except at creation)
          required: true
          description: >-
            The URL where the HTTP POST requests will be made. To identify the
            source of the webhook on your notifications server, you can use the
            `url`'s hostname, path or query parameters. For example:


            ```json

            {
              "url": "https://${username}.my-notifications.com/${my-secret}/?param1=value1&param2=value2"
            }

            ```
          type: string
        minIntervalMs:
          readOnly: true
          required: true
          description: The webhooks run rate is throttled by a minimum interval between
            HTTP calls in milliseconds, sending an array of changes that occured
            during this period. Its value is set by the platform admin.
          type: number
        maxRetries:
          readOnly: true
          required: true
          description: In case of failure to send a request, the webhook will retry
            `maxRetries` times at a growing interval of time before becoming
            `inactive` after too many successive failures. Its value is set by
            the platform admin.
          type: number
        currentRetries:
          readOnly: true
          required: true
          description: The number of retries iterations since the last failed HTTP call.
            This number is 0 if the last HTTP call was successful.
          type: number
        state:
          required: true
          description: The current state of the Webhook. An inactive Webhook will not make
            any HTTP call when changes occur. It must be activated using the
            [update webhook](#methods-webhooks-webhooks-update) method.
          schema:
            type: string
            enum:
              - active
              - inactive
        runCount:
          readOnly: true
          required: true
          description: The number of times the Webhook has been run, including failures.
          type: number
        failCount:
          readOnly: true
          required: true
          description: The number of times the Webhook has failed HTTP calls. Failed runs
            are HTTP requests that received a response with a status outside of
            the 200-299 range or no response at all.
          type: number
        lastRun:
          readOnly: true
          required: true
          description: Represents the last Webhook call, comprised of its HTTP response
            status and timestamp.
          type: Run object
        runs:
          readOnly: true
          required: true
          description: Array of Run objects in inverse chronological order (newest first)
            which allows to monitor a webhook's health. Its length is set by the
            platform admin.
          type: array
          items:
            type: Run objects
        scopes:
          description: >-
            Optional map of **named scopes** that restrict the webhook to
            specific changes. When omitted, the webhook fires on every change in
            the account (default, unfiltered behaviour).


            Each entry is keyed by a name you choose and has the shape `{ kind, query }`:


            - `kind` — one of `events` (default), `streams` or `accesses`.

            - `query` — a filter shaped like the parameters of the matching read method: an [events.get](#get-events) query for `events` (`streams`, `types`, `content`, `clientData`), a `{ streams }` query for `streams`, or an accesses filter for `accesses`.


            A scoped webhook receives notifications **only** for changes matching one of its scopes. Instead of the coarse `eventsChanged` / `streamsChanged` messages, the [data changes payload](#with-webhooks) then carries the **matched scope keys** — so your endpoint knows *which* subscription fired without inspecting the data:


            ```json

            {
              "scopes": {
                "newReadings": { "kind": "events", "query": { "streams": ["measurements"], "types": ["mass/kg"] } },
                "structure":   { "kind": "streams", "query": { "streams": ["measurements"] } }
              }
            }

            ```


            `scopes` is alterable: include it in an [update webhook](#methods-webhooks-webhooks-update) call to change the subscriptions of an existing webhook.
          type: object
        created:
          readOnly: true
          required: true
          description: The time the webhook was created.
          $ref: "#/components/schemas/timestamp"
        createdBy:
          readOnly: true
          required: true
          description: The id of the access used to create the webhook.
          $ref: "#/components/schemas/identifier"
        modified:
          readOnly: true
          required: true
          description: The time the webhook was last modified.
          $ref: "#/components/schemas/timestamp"
        modifiedBy:
          readOnly: true
          required: true
          description: The id of the last access used to modify the webhook.
          $ref: "#/components/schemas/identifier"
    item-deletion:
      type: object
      properties:
        id:
          required: true
          description: The identifier of the deleted item.
          $ref: "#/components/schemas/identifier"
        deleted:
          description: The time the item was deleted.
          $ref: "#/components/schemas/timestamp"
    key-value:
      type: object
      additionalProperties: true
    error:
      type: object
      properties:
        id:
          required: true
          description: Identifier for the error.
          type: string
        message:
          required: true
          description: A human-readable description of the error.
          type: string
        data:
          description: Additional machine-readable details (specified for each error if
            relevant).
          type: any type
        subErrors:
          description: Lists the detailed causes of the main error, if any.
          type: array
          items:
            type: errors
    streams-query: {}
    content-query: {}
    identifier:
      type: string
    timestamp:
      type: number
    integrity: {}