{
  "openapi": "3.1.0",
  "info": {
    "title": "Sonaline partner API",
    "version": "1",
    "description": "A partner's own systems making and looking after its workspaces from the outside, and reading its bills. The guide: https://sonaline.com/developers/partner",
    "contact": {
      "email": "hello@sonaline.com"
    }
  },
  "servers": [
    {
      "url": "https://api.sonaline.com/api/v1/partners/{accountId}",
      "variables": {
        "accountId": {
          "default": "0000000",
          "description": "Your account number, shown beside your credentials."
        }
      }
    }
  ],
  "paths": {
    "/api/v1/partners/oauth2/token": {
      "post": {
        "operationId": "post_oauth2_token",
        "summary": "Get a bearer token, good for an hour, for a client id and secret (OAuth 2 client credentials).",
        "x-sonaline-token-door": true,
        "x-sonaline-effect": "changes",
        "servers": [
          {
            "url": "https://api.sonaline.com"
          }
        ],
        "security": [
          {
            "basic": []
          },
          {}
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "client_credentials"
                    ]
                  },
                  "client_id": {
                    "type": "string",
                    "description": "Instead of Basic: the client id."
                  },
                  "client_secret": {
                    "type": "string",
                    "writeOnly": true,
                    "format": "password",
                    "description": "Instead of Basic: the secret. Never in a query string."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A token.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "access_token",
                    "token_type",
                    "expires_in"
                  ],
                  "properties": {
                    "access_token": {
                      "type": "string"
                    },
                    "access_token_id": {
                      "type": "string"
                    },
                    "token_type": {
                      "type": "string",
                      "enum": [
                        "Bearer"
                      ]
                    },
                    "expires_in": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/OAuthError"
          },
          "401": {
            "$ref": "#/components/responses/OAuthError"
          },
          "405": {
            "$ref": "#/components/responses/OAuthError"
          },
          "413": {
            "$ref": "#/components/responses/OAuthError"
          },
          "429": {
            "$ref": "#/components/responses/OAuthError"
          },
          "503": {
            "$ref": "#/components/responses/OAuthError"
          }
        }
      }
    },
    "/billing": {
      "get": {
        "operationId": "get_billing",
        "summary": "Read your bill for a month.",
        "security": [
          {
            "bearer": [
              "billing:read"
            ]
          },
          {
            "basic": [
              "billing:read"
            ]
          }
        ],
        "x-sonaline-scope": "billing:read",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "parameters": [
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 7,
              "maxLength": 7
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/invoices": {
      "get": {
        "operationId": "get_invoices",
        "summary": "List your invoices.",
        "security": [
          {
            "bearer": [
              "billing:read"
            ]
          },
          {
            "basic": [
              "billing:read"
            ]
          }
        ],
        "x-sonaline-scope": "billing:read",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/webhooks": {
      "get": {
        "operationId": "get_webhooks",
        "summary": "List your webhooks, without their secrets, and the events they can hear.",
        "security": [
          {
            "bearer": [
              "events:write"
            ]
          },
          {
            "basic": [
              "events:write"
            ]
          }
        ],
        "x-sonaline-scope": "events:write",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "post": {
        "operationId": "post_webhooks",
        "summary": "Add a webhook: an HTTPS endpoint and the events it hears. The answer shows its signing secret, once.",
        "description": "Takes no Idempotency-Key: its answer holds the secret, which Sonaline keeps only sealed.",
        "security": [
          {
            "bearer": [
              "events:write"
            ]
          },
          {
            "basic": [
              "events:write"
            ]
          }
        ],
        "x-sonaline-scope": "events:write",
        "x-sonaline-rate": "changes",
        "x-sonaline-effect": "changes",
        "x-sonaline-confirm": true,
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2000
                  },
                  "events": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 8
                  }
                },
                "required": [
                  "url",
                  "events"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedType"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyMismatch"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/webhooks/{webhookId}": {
      "get": {
        "operationId": "get_webhooks_by_webhook",
        "summary": "Read one of your webhooks.",
        "security": [
          {
            "bearer": [
              "events:write"
            ]
          },
          {
            "basic": [
              "events:write"
            ]
          }
        ],
        "x-sonaline-scope": "events:write",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "description": "One of your webhooks' id, from GET /webhooks.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "patch": {
        "operationId": "patch_webhooks_by_webhook",
        "summary": "Change a webhook's address or events, or switch it off or back on.",
        "security": [
          {
            "bearer": [
              "events:write"
            ]
          },
          {
            "basic": [
              "events:write"
            ]
          }
        ],
        "x-sonaline-scope": "events:write",
        "x-sonaline-rate": "changes",
        "x-sonaline-effect": "changes",
        "x-sonaline-confirm": true,
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "description": "One of your webhooks' id, from GET /webhooks.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "url": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 2000
                  },
                  "events": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 8
                  },
                  "enabled": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedType"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyMismatch"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "delete": {
        "operationId": "delete_webhooks_by_webhook",
        "summary": "Remove a webhook and its delivery log.",
        "security": [
          {
            "bearer": [
              "events:write"
            ]
          },
          {
            "basic": [
              "events:write"
            ]
          }
        ],
        "x-sonaline-scope": "events:write",
        "x-sonaline-rate": "changes",
        "x-sonaline-effect": "changes",
        "x-sonaline-confirm": true,
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "description": "One of your webhooks' id, from GET /webhooks.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyMismatch"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/webhooks/{webhookId}/deliveries": {
      "get": {
        "operationId": "get_webhooks_by_webhook_deliveries",
        "summary": "Read a webhook's delivery log, newest first.",
        "security": [
          {
            "bearer": [
              "events:write"
            ]
          },
          {
            "basic": [
              "events:write"
            ]
          }
        ],
        "x-sonaline-scope": "events:write",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "description": "One of your webhooks' id, from GET /webhooks.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/webhooks/{webhookId}/test": {
      "post": {
        "operationId": "post_webhooks_by_webhook_test",
        "summary": "Send a ping to a webhook at once and say what it answered.",
        "security": [
          {
            "bearer": [
              "events:write"
            ]
          },
          {
            "basic": [
              "events:write"
            ]
          }
        ],
        "x-sonaline-scope": "events:write",
        "x-sonaline-rate": "changes",
        "x-sonaline-effect": "sends",
        "x-sonaline-confirm": true,
        "x-sonaline-unknown-outcome-keeps-key": true,
        "parameters": [
          {
            "name": "webhookId",
            "in": "path",
            "required": true,
            "description": "One of your webhooks' id, from GET /webhooks.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {},
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedType"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyMismatch"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/workspaces": {
      "get": {
        "operationId": "get_workspaces",
        "summary": "List your workspaces, a page at a time.",
        "security": [
          {
            "bearer": [
              "workspaces:read"
            ]
          },
          {
            "basic": [
              "workspaces:read"
            ]
          }
        ],
        "x-sonaline-scope": "workspaces:read",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 200
            }
          },
          {
            "name": "after",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "maxLength": 64
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "post": {
        "operationId": "post_workspaces",
        "summary": "Make a workspace, on your default prices and within your limits.",
        "security": [
          {
            "bearer": [
              "workspaces:write"
            ]
          },
          {
            "basic": [
              "workspaces:write"
            ]
          }
        ],
        "x-sonaline-scope": "workspaces:write",
        "x-sonaline-rate": "changes",
        "x-sonaline-effect": "changes",
        "x-sonaline-confirm": true,
        "x-sonaline-unknown-outcome-keeps-key": true,
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "workspace": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 40
                  },
                  "display_name": {
                    "type": "string",
                    "maxLength": 80
                  }
                },
                "required": [
                  "workspace"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedType"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyMismatch"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/workspaces/{workspaceId}": {
      "get": {
        "operationId": "get_workspaces_by_workspace",
        "summary": "Read one of your workspaces.",
        "security": [
          {
            "bearer": [
              "workspaces:read"
            ]
          },
          {
            "basic": [
              "workspaces:read"
            ]
          }
        ],
        "x-sonaline-scope": "workspaces:read",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "path",
            "required": true,
            "description": "A workspace's full name, such as acme_plumbing.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      },
      "patch": {
        "operationId": "patch_workspaces_by_workspace",
        "summary": "Change one workspace's name or features.",
        "security": [
          {
            "bearer": [
              "workspaces:write"
            ]
          },
          {
            "basic": [
              "workspaces:write"
            ]
          }
        ],
        "x-sonaline-scope": "workspaces:write",
        "x-sonaline-rate": "changes",
        "x-sonaline-effect": "changes",
        "x-sonaline-confirm": true,
        "parameters": [
          {
            "name": "workspaceId",
            "in": "path",
            "required": true,
            "description": "A workspace's full name, such as acme_plumbing.",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "display_name": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 80
                  },
                  "sms": {
                    "type": "string",
                    "enum": [
                      "on",
                      "off"
                    ]
                  },
                  "calls_enabled": {
                    "type": "boolean"
                  },
                  "voicemail_enabled": {
                    "type": "boolean"
                  },
                  "app_enabled": {
                    "type": "boolean"
                  }
                },
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "409": {
            "$ref": "#/components/responses/Conflict"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "415": {
            "$ref": "#/components/responses/UnsupportedType"
          },
          "422": {
            "$ref": "#/components/responses/IdempotencyMismatch"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "502": {
            "$ref": "#/components/responses/BadGateway"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    },
    "/workspaces/{workspaceId}/usage": {
      "get": {
        "operationId": "get_workspaces_by_workspace_usage",
        "summary": "Read one workspace's usage and price for a month.",
        "security": [
          {
            "bearer": [
              "billing:read"
            ]
          },
          {
            "basic": [
              "billing:read"
            ]
          }
        ],
        "x-sonaline-scope": "billing:read",
        "x-sonaline-rate": "reads",
        "x-sonaline-effect": "reads",
        "parameters": [
          {
            "name": "workspaceId",
            "in": "path",
            "required": true,
            "description": "A workspace's full name, such as acme_plumbing.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "month",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 7,
              "maxLength": 7
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Done.",
            "headers": {
              "Sonaline-Request-Id": {
                "$ref": "#/components/headers/RequestId"
              },
              "RateLimit-Limit": {
                "$ref": "#/components/headers/RateLimitLimit"
              },
              "RateLimit-Remaining": {
                "$ref": "#/components/headers/RateLimitRemaining"
              },
              "RateLimit-Reset": {
                "$ref": "#/components/headers/RateLimitReset"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Invalid"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "405": {
            "$ref": "#/components/responses/MethodNotAllowed"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/Failed"
          },
          "503": {
            "$ref": "#/components/responses/Unavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "oauth2",
        "description": "A token from the token door, good for an hour, sent as Authorization: Bearer.",
        "flows": {
          "clientCredentials": {
            "tokenUrl": "https://api.sonaline.com/api/v1/partners/oauth2/token",
            "scopes": {
              "workspaces:read": "Read your workspaces.",
              "workspaces:write": "Make a workspace, and change its name and its features.",
              "billing:read": "Read your bills, invoices and one workspace's usage.",
              "events:write": "Register, change and test the endpoints that hear your events, and read their delivery log."
            }
          }
        }
      },
      "basic": {
        "type": "http",
        "scheme": "basic",
        "description": "The client id and secret on each request."
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "1 to 100 visible characters. The same request with the same key is answered once; its first answer is given again for 24 hours.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        }
      }
    },
    "headers": {
      "RequestId": {
        "description": "Made by Sonaline for this request. Quote it to support.",
        "schema": {
          "type": "string"
        }
      },
      "RateLimitLimit": {
        "description": "The most requests of this kind in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitRemaining": {
        "description": "What is left in the window.",
        "schema": {
          "type": "integer"
        }
      },
      "RateLimitReset": {
        "description": "Seconds until the window resets.",
        "schema": {
          "type": "integer"
        }
      }
    },
    "responses": {
      "Invalid": {
        "description": "A field is missing or wrong (`invalid`, with `field`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unauthorized": {
        "description": "No credential, or a wrong or expired one (`unauthorized`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "Not this credential's account, or a scope or switch refuses it.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No such thing on this account (`not_found`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "MethodNotAllowed": {
        "description": "A method the path does not take; Allow names the ones it does.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Allow": {
            "schema": {
              "type": "string"
            }
          }
        }
      },
      "Conflict": {
        "description": "The route's own conflict (a name taken, a limit reached), or a request with this Idempotency-Key still running or with no answer.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "TooLarge": {
        "description": "The body is over its size (`payload_too_large`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UnsupportedType": {
        "description": "The body is not of a type the route takes.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Failed": {
        "description": "Something failed on Sonaline's side, or a carrier refused.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "BadGateway": {
        "description": "The service behind the API failed or did not answer (`box_unreachable`). Try again in a moment.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "GatewayTimeout": {
        "description": "The service behind the API did not answer in time: what was asked may have been done. Check before trying again.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Unavailable": {
        "description": "Not available just now: try again in a moment.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        }
      },
      "OAuthError": {
        "description": "OAuth 2's error body (RFC 6749): {error, error_description}. A 429 carries Retry-After, a 405 Allow.",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "required": [
                "error"
              ],
              "properties": {
                "error": {
                  "type": "string"
                },
                "error_description": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "IdempotencyMismatch": {
        "description": "The Idempotency-Key was used on another request (`idempotency_mismatch`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Too many requests (`rate_limited`): wait Retry-After seconds.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "headers": {
          "Retry-After": {
            "schema": {
              "type": "integer"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message",
              "status"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable: what to act on."
              },
              "message": {
                "type": "string",
                "description": "Plain words; may change."
              },
              "status": {
                "type": "integer"
              },
              "field": {
                "type": "string",
                "description": "The field that is wrong, for `invalid`."
              }
            }
          }
        }
      }
    }
  }
}
