Cobot Navigation Link API

openapi: 3.2.0
info:
  title: Cobot Navigation Link API
  termsOfService: https://www.cobot.me/terms
  x-logo:
    url: /api2_logo.webp
    backgroundColor: '#FFFFFF'
    altText: Cobot logo
  description: "This is the 2.0 version of the Cobot API. You can find version 1.0\nas well as various tutorials under [/api-docs](/api-docs).\n\n## JSON API\n\nThis API follows the [JSON API](http://jsonapi.org) standard. This means:\n\n* requests and responses are sent in JSON\n* all requests MUST send a `Accept: application/vnd.api+json` header\n* non-GET requests MUST send a `Content-Type: application/vnd.api+json` header\n* all responses send a `Content-Type: application/vnd.api+json` header\n* all JSON formats are standardized (requests, responses, errors)\n\n## Cross-Origin Resource Sharing (CORS)\n\nAll endpoints send [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS)\nheaders so that the API can be used from within browsers.\n\n## Rate Limiting\n\nIn general, the rate limit for an endpoint is 60 requests per minute per user.\nIf applicable, alternative limits are given in the documentation for\nparticular endpoints.\n\nIf you've exceeded the limit, Cobot will return a 429 status code and a JSON\nerror message. The response will also contain a *Retry-After* header, this\ndenotes the number of seconds to wait before your client may retry.\n\n## Times and Dates\n\nTimes and Dates must be in ISO 8601 formats. e.g. date: `2021-01-07`, datetime: `2021-01-07T16:25:51Z`,  time: `16:25:51`.\nMillisecond are ommited, so `16:25:51.811` will become `16:25:51`.\nTime zone offsets must be provided by the client, e.g. `16:25:51+02:00` or '16:25:51Z' for UTC.\n\nTimes are always returned in UTC.\n## Sparse Fieldsets\n\nThis API supports [sparse fieldsets](https://jsonapi.org/format/#fetching-sparse-fieldsets),\nso clients can request which attributes they are interested in.\n\nExample:\n```\nGET https://api.cobot.me/user?fields[users]=email\n```\nThis will only return the user's email.\n\n## Query params\n\nWhen passing query params, arrays of data are expected to be sent as a string of comma separated values.\n\n## Pagination\n\nAll collections are paginated. Pagination follows [JSON-API standards](https://jsonapi.org/format/#fetching-pagination).\n\nExample:\n```json\n{\n  \"meta\": {\n    \"totalPages\": 2,\n    \"currentPage\": 1\n  },\n  \"data\": [{\n    \"id\": \"1\",\n    \"type\": \"users\",\n  }],\n  \"links\": {\n    \"self\": \"/users?page[size]=100&page[number]=1\",\n    \"first\": \"/users?page[size]=100&page[number]=1\",\n    \"prev\": null,\n    \"next\": \"/users?page[size]=100&page[number]=2\",\n    \"last\": \"/users?page[size]=100&page[number]=1\"\n  }\n}\n```\n\nDefault page size is 72 and can be changed by passing a `page[size]` parameter. Maximum page size is 200.\n\n## Errors\n\nWhen a client sends invalid data in a request, Cobot returns a\n422 status code and a JSON-API error response.\n\nExample:\n```json\n{\n  \"errors\": [\n    {\n      \"source\": {\n        \"pointer\": \"/data/attributes/name\"\n      },\n      \"detail\": \"can't be blank\"\n    },\n    {\n      \"source\": {\n        \"pointer\": \"/data/attributes/password\"\n      },\n      \"detail\": \"is too short\"\n    }\n  ]\n}\n```\n"
  version: '2.0'
  contact:
    name: Cobot Support
    url: https://dev.cobot.me/
    email: support@cobot.me
servers:
- url: https://api.cobot.me
security:
- OAuth2: []
tags:
- name: Navigation Link
  description: Navigation links allow you to embed 3rd party apps on a space's Cobot UI. See also the single page app endpoints.
paths:
  /navigation_links:
    post:
      summary: Create
      description: "Create a navigation link.\n\nNavigation links create new entries in the navigation of a space, either\nin the admin or member section. This allows you to show users content/apps\ncreated not by Cobot.\n\nWhen creating a navigation link, you have to pass a single page app as\na relationship. This app's CSS/JS is going to be embedded on Cobot\non the new page created by the navigation link.\n\nTo embed an iframe or create an external link instead of embedding \na single page app, see the navigation link endpoints in API 1.\n"
      operationId: create-navigation-link
      security:
      - OAuth2:
        - write_navigation_links
      tags:
      - Navigation Link
      responses:
        '201':
          description: The new navigation link.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/navigation-link'
              examples:
                default:
                  value:
                    data:
                      id: 0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                      type: navigationLinks
                      attributes:
                        label: External App
                        section: admin/manage
                        userUrl: https://demo.cobot.me/admin/navigation_links/0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                      relationships:
                        space:
                          data:
                            id: bac10fb5-f3a4-5597-9af6-846d7561cec4
                            type: spaces
                        singlePageApp:
                          data:
                            id: cc63f516-e1e3-57b1-9825-5d937235c66f
                            type: singlePageApps
        '422':
          description: 'Creating the navigation link failed because of missing/invalid data.

            '
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/failure'
              examples:
                default:
                  value:
                    errors:
                    - source:
                        pointer: /data/attributes/label
                      detail: can't be empty
      requestBody:
        description: The attributes and relationships.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/create-navigation-link'
            examples:
              default:
                value:
                  data:
                    type: navigationLinks
                    attributes:
                      label: External app
                      section: admin/setup
                    relationships:
                      space:
                        data:
                          id: a2461baa-0661-5d7f-a8ff-dcbde5632001
                          type: spaces
                      singlePageApp:
                        data:
                          id: 70b0ed4a-43a3-5864-b238-99fed02ba5aa
                          type: singlePageApps
  /navigation_links/{id}:
    patch:
      summary: Update
      description: 'Update a navigation link.

        '
      operationId: update-navigation-link
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the navigation link.
        schema:
          type: string
      security:
      - OAuth2:
        - write_navigation_links
      tags:
      - Navigation Link
      responses:
        '200':
          description: The updated navigation link.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/navigation-link'
              examples:
                default:
                  value:
                    data:
                      id: 0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                      type: navigationLinks
                      attributes:
                        label: External App
                        section: admin/manage
                        userUrl: https://demo.cobot.me/admin/navigation_links/0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                      relationships:
                        space:
                          data:
                            id: bac10fb5-f3a4-5597-9af6-846d7561cec4
                            type: spaces
                        singlePageApp:
                          data:
                            id: cc63f516-e1e3-57b1-9825-5d937235c66f
                            type: singlePageApps
      requestBody:
        description: The attributes to update.
        required: true
        content:
          application/vnd.api+json:
            schema:
              $ref: '#/components/schemas/update-navigation-link'
            examples:
              default:
                value:
                  data:
                    type: navigationLinks
                    id: 0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                    attributes:
                      label: New label
                      section: admin/setup
    get:
      summary: Single link
      description: 'Fetch a single navigation link.

        '
      operationId: get-navigation-link
      parameters:
      - name: id
        in: path
        required: true
        description: The id of the navigation link.
        schema:
          type: string
      security:
      - OAuth2:
        - read_navigation_links
      tags:
      - Navigation Link
      responses:
        '200':
          description: The navigation link.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/navigation-link'
              examples:
                default:
                  value:
                    data:
                      id: 0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                      type: navigationLinks
                      attributes:
                        label: External App
                        section: admin/manage
                        userUrl: https://demo.cobot.me/admin/navigation_links/0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                      relationships:
                        space:
                          data:
                            id: bac10fb5-f3a4-5597-9af6-846d7561cec4
                            type: spaces
                        singlePageApp:
                          data:
                            id: cc63f516-e1e3-57b1-9825-5d937235c66f
                            type: singlePageApps
  /spaces/{spaceId}/navigation_links:
    get:
      summary: List for space
      description: 'List the navigation links for a space. This will only list the links the current OAuth app created.

        '
      operationId: get-space-navigation-links
      parameters:
      - name: spaceId
        in: path
        required: true
        description: The id of the space.
        schema:
          type: string
      security:
      - OAuth2:
        - read_navigation_links
      tags:
      - Navigation Link
      responses:
        '200':
          description: The navigation links.
          content:
            application/vnd.api+json:
              schema:
                $ref: '#/components/schemas/navigation-links'
              examples:
                default:
                  value:
                    data:
                    - id: 0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                      type: navigationLinks
                      attributes:
                        label: External App
                        section: admin/manage
                        userUrl: https://demo.cobot.me/admin/navigation_links/0952499e-82dc-59f1-b6aa-fcac8f2bccf9
                      relationships:
                        space:
                          data:
                            id: bac10fb5-f3a4-5597-9af6-846d7561cec4
                            type: spaces
                        singlePageApp:
                          data:
                            id: cc63f516-e1e3-57b1-9825-5d937235c66f
                            type: singlePageApps
components:
  schemas:
    create-navigation-link:
      id: create-navigation-link.json#
      type: object
      required:
      - data
      additionalProperties: false
      properties:
        data:
          type: object
          required:
          - type
          - relationships
          - attributes
          additionalProperties: false
          properties:
            type:
              type: string
              enum:
              - navigationLinks
            attributes:
              type: object
              additionalProperties: false
              required:
              - label
              - section
              properties:
                label:
                  type: string
                section:
                  type: string
                  enum:
                  - admin/setup
                  - admin/manage
                  - admin/analyze
                  - members
            relationships:
              type: object
              additionalProperties: false
              required:
              - space
              - singlePageApp
              properties:
                space:
                  type: object
                  additionalProperties: false
                  required:
                  - data
                  properties:
                    data:
                      type: object
                      required:
                      - type
                      - id
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - spaces
                        id:
                          type: string
                singlePageApp:
                  type: object
                  additionalProperties: false
                  required:
                  - data
                  properties:
                    data:
                      type: object
                      required:
                      - type
                      - id
                      additionalProperties: false
                      properties:
                        type:
                          type: string
                          enum:
                          - singlePageApps
                        id:
                          type: string
    link:
      description: 'A link **MUST** be represented as either: a string containing the link''s URL or a link object.'
      oneOf:
      - description: A string containing the link's URL.
        type: string
        format: uri-reference
      - type: object
        required:
        - href
        properties:
          href:
            description: A string containing the link's URL.
            type: string
            format: uri-reference
          meta:
            $ref: '#/components/schemas/meta'
    error:
      type: object
      properties:
        id:
          description: A unique identifier for this particular occurrence of the problem.
          type: string
        links:
          $ref: '#/components/schemas/links'
        status:
          description: The HTTP status code applicable to this problem, expressed as a string value.
          type: string
        code:
          description: An application-specific error code, expressed as a string value.
          type: string
        title:
          description: A short, human-readable summary of the problem. It **SHOULD NOT** change from occurrence to occurrence of the problem, except for purposes of localization.
          type: string
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        source:
          type: object
          properties:
            pointer:
              description: A JSON Pointer [RFC6901] to the associated entity in the request document [e.g. "/data" for a primary data object, or "/data/attributes/title" for a specific attribute].
              type: string
            parameter:
              description: A string indicating which query parameter caused the error.
              type: string
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    jsonapi:
      description: An object describing the server's implementation
      type: object
      properties:
        version:
          type: string
        meta:
          $ref: '#/components/schemas/meta'
      additionalProperties: false
    links:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/link'
    update-navigation-link:
      id: update-navigation-link.json#
      type: object
      required:
      - data
      additionalProperties: false
      properties:
        data:
          type: object
          required:
          - type
          - id
          - attributes
          additionalProperties: false
          properties:
            type:
              type: string
              enum:
              - navigationLinks
            id:
              type: string
            attributes:
              type: object
              additionalProperties: false
              properties:
                label:
                  type: string
                section:
                  type: string
                  enum:
                  - admin/setup
                  - admin/manage
                  - admin/analyze
                  - members
    meta:
      description: Non-standard meta-information that can not be represented as an attribute or relationship.
      type: object
      additionalProperties: true
    navigation-link:
      id: navigation-link.json#
      type: object
      required:
      - data
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/-navigation-link-data'
    -navigation-link-data:
      id: -navigation-link-data.json#
      type: object
      required:
      - type
      - id
      - relationships
      - attributes
      additionalProperties: false
      properties:
        id:
          type: string
        type:
          type: string
          enum:
          - navigationLinks
        attributes:
          type: object
          additionalProperties: false
          required:
          - label
          - section
          - userUrl
          properties:
            label:
              type: string
              description: The label used for the link in the space's navigation.
            userUrl:
              type: string
              format: uri
              description: The URL users should visit in the space's UI to see the navigation link's content.
            section:
              type: string
              enum:
              - admin/setup
              - admin/manage
              - admin/analyze
              - members
              description: Where in a space's UI to embed the link.
        relationships:
          type: object
          additionalProperties: false
          required:
          - space
          properties:
            space:
              type: object
              additionalProperties: false
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - type
                  - id
                  additionalProperties: false
                  properties:
                    type:
                      type: string
                      enum:
                      - spaces
                    id:
                      type: string
            singlePageApp:
              type: object
              additionalProperties: false
              required:
              - data
              properties:
                data:
                  type: object
                  required:
                  - type
                  - id
                  additionalProperties: false
                  properties:
                    type:
                      type: string
                      enum:
                      - singlePageApps
                    id:
                      type: string
    pagination-links:
      type: object
      required:
      - first
      - self
      - next
      additionalProperties: false
      properties:
        first:
          type: string
          description: Link to the first results page.
        prev:
          oneOf:
          - type: string
          - type: 'null'
          description: Link to the previous results page. Null when on the first page.
        self:
          type: string
          description: Link to the current results page.
        next:
          oneOf:
          - type: string
          - type: 'null'
          description: Link to the next results page. Null when on the last page.
        last:
          type: string
          description: Link to the last results page.
    pagination-meta:
      type: object
      additionalProperties: false
      properties:
        totalPages:
          type: number
        currentPage:
          type: number
    navigation-links:
      id: navigation-link.json#
      type: object
      required:
      - data
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/-navigation-link-data'
        links:
          $ref: '#/components/schemas/pagination-links'
        meta:
          $ref: '#/components/schemas/pagination-meta'
    failure:
      type: object
      required:
      - errors
      properties:
        errors:
          type: array
          items:
            $ref: '#/components/schemas/error'
          uniqueItems: true
        meta:
          $ref: '#/components/schemas/meta'
        jsonapi:
          $ref: '#/components/schemas/jsonapi'
        links:
          $ref: '#/components/schemas/links'
      additionalProperties: false
  securitySchemes:
    OpenId:
      type: openIdConnect
      openIdConnectUrl: https://www.cobot.me/.well-known/openid-configuration
    OAuth2:
      type: oauth2
      description: "OAuth is \"an open protocol to allow secure API authorization in a simple and\nstandard method from desktop and web applications.\". \"OAuth 2.0 is the\nnext evolution of the OAuth protocol [..]. OAuth 2.0 focuses on client\ndeveloper simplicity [...]. It is supported by many popular sites such as\nFacebook and there are client libraries available for many programming\nlanguages.\n\nFor information about OAuth2 see the [oauth website](http://oauth.net/2/).\n\n**For OAuth2 you need a client id and secret. In order to get those you have\nto [register your application](/oauth2_clients).**\n\nAPI authorization works by passing a bearer token via the HTTP Authorization header:\n\n    Authorization: bearer <token>\n\n## Permissions (Scope)\n\nOAuth2 [defines scopes](https://tools.ietf.org/html/rfc6749#section-3.3) to\nrestrict access to certain resources.\n\nThe required scope for each resource can be found within the documentation\nfor each endpoint.\n\nPlease note that a user's scope can be limited when they access the API as\nan admin of a space and some of their admin permissions have been revoked.\n"
      flows:
        authorizationCode:
          authorizationUrl: https://www.cobot.me/oauth/authorize
          tokenUrl: https://www.cobot.me/oauth/access_token
          scopes:
            read_articles: Read help desk articles.
            read_allocations: Read resource allocation data.
            read_booking_credits: Read information about a membership's booking credits.
            read_bookings: Read booking data.
            read_built_in_email_customizations: Read built in email customizations.
            read_calendar_blockers: Read calendar blockers.
            read_check_ins: Read memberships' check-in data.
            read_contacts: Read contacts.
            read_drop_in_passes: Read drop-in passes.
            read_drop_in_pass_templates: Read drop-in pass templates.
            read_discount_codes: Read discount codes.
            read_event_attendances: Read who is attending an event.
            read_event_messages: Read messages sent about events.
            read_events: Read events of a space.
            read_external_bookings: Read external booking data.
            read_external_resources: Read resources enabled for external booking.
            read_invoices: Read invoices created for a membership in a space.
            read_memberships: Read information about memberships in a space.
            read_teams: Read information about teams in a space.
            read_membership_profiles: Read members' profile data.
            read_navigation_links: Read/list navigation links for a space.
            read_payment_methods: Read payment methods in order to process payments.
            read_published_membership_profiles: Read published members' profile data.
            read_networks: Read information about a network.
            read_products: Read information about products.
            read_resource_categories: Read information about booking calendar categories.
            read_resources: Read information about booking calendar resources.
            read_single_page_apps: Read information about single page apps.
            read_space_profiles: Read space profile information.
            read_spaces: Read basic space information.
            read_space_billing_details: Read information relevant to billing the space.
            read_space_payment_method: Read a space's payment method used to pay for the space's Cobot subscription.
            read_space_subscriptions: Read a space's subscription.
            read_terms_approvals: Shows missing approvals for the current member.
            read_urls: Read the URLs to the Cobot web interface.
            read_user: Read the current user's information.
            write_bookings: Write booking data.
            write_check_ins: Check a member in at a space.
            write_customers: Convert a space to a customer.
            write_drop_in_pass_purchases: Create drop-in pass purchases.
            write_drop_in_passes: Cancel drop-in passes.
            write_event_ticket_purchases: Create event ticket purchases.
            write_event_attendances: Attend/unattend events.
            write_event_messages: Create/update messages sent about events.
            write_events: Write to events of a space.
            write_external_bookings: Create/update bookings as a non-member.
            write_external_resources: Create/update/delete resources enabled for non-memberss
            write_resources: Create/update/delete booking calendar resources.
            write_invoices: Create invoices for members in a space.
            write_invoice_reminders: Send invoice reminder emails.
            write_membership_profiles: Manage the social profiles of members.
            write_navigation_links: Create/update/delete navigation links for a space.
            write_payments: Initiate payments for external bookings.
            write_single_page_apps: Create and update single page apps to be embedded on Cobot.
            write_space_billing_details: Update a space's billing details.
            write_space_payment_method: Update a space's payment method used to pay for the space's Cobot subscription.
            write_space_subscriptions: Change a space's subscription. Only trusted clients can request this scope. Contact support.
            write_terms_approvals: Approve different kinds of terms as a member.