{
  "openapi": "3.1.0",
  "info": {
    "title": "Pinal API",
    "version": "1.0.0",
    "summary": "Mail, contacts, calendars, passwords, notes and photos, over OAuth 2.",
    "description": "The same API Pinal's own apps use. Authenticate with OAuth 2 (authorization code + PKCE) through Pinal Accounts, then call the endpoints below with the access token as a Bearer token. Each operation lists the scope it needs.",
    "contact": {
      "name": "Pinal Developers",
      "url": "https://developers.pinal.tech"
    },
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.pinal.tech/v1",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "Sign in with Pinal",
      "description": "OAuth 2.1 and OpenID Connect on Pinal Accounts: send people to sign in, get tokens, find out who they are."
    },
    {
      "name": "Developer",
      "description": "Manage your apps programmatically. The same API the Developers dashboard uses."
    },
    {
      "name": "Mail",
      "description": "Messages, drafts and labels in Pinal Mail."
    },
    {
      "name": "Contacts",
      "description": "The people in someone's address book."
    },
    {
      "name": "Calendar",
      "description": "Events and free/busy time."
    },
    {
      "name": "Passwords",
      "description": "Zero-knowledge vault access. Items are encrypted on the person's devices."
    },
    {
      "name": "Notes",
      "description": "Notes, notebooks and sharing."
    },
    {
      "name": "Photos",
      "description": "Libraries, albums and uploads."
    }
  ],
  "paths": {
    "/.well-known/openid-configuration": {
      "get": {
        "tags": [
          "Sign in with Pinal"
        ],
        "operationId": "discovery",
        "summary": "Discovery document",
        "description": "OpenID Connect discovery metadata: every endpoint, supported scope, grant and signing algorithm. Point your OIDC library here and it configures itself.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Provider metadata",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                },
                "example": {
                  "issuer": "https://accounts.pinal.tech",
                  "authorization_endpoint": "https://accounts.pinal.tech/api/auth/oauth2/authorize",
                  "token_endpoint": "https://accounts.pinal.tech/api/auth/oauth2/token",
                  "userinfo_endpoint": "https://accounts.pinal.tech/api/auth/oauth2/userinfo",
                  "jwks_uri": "https://accounts.pinal.tech/api/auth/jwks",
                  "code_challenge_methods_supported": [
                    "S256"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/oauth2/authorize": {
      "get": {
        "tags": [
          "Sign in with Pinal"
        ],
        "operationId": "authorize",
        "summary": "Start sign-in",
        "description": "Send the person's browser here. They sign in to Pinal Accounts (if they aren't already), see your app's consent screen, and come back to `redirect_uri` with a `code` and your `state`. PKCE (S256) is required for every app.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [],
        "parameters": [
          {
            "name": "response_type",
            "in": "query",
            "description": "Always `code`.",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "code"
              ]
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "description": "Your app's client ID.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "pnl_7Hq2xV9kLmA1"
          },
          {
            "name": "redirect_uri",
            "in": "query",
            "description": "One of your app's redirect URIs, exactly as registered.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "scope",
            "in": "query",
            "description": "Space-separated scopes. Must be a subset of the scopes your app is allowed.",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "openid profile email"
          },
          {
            "name": "state",
            "in": "query",
            "description": "An unguessable value you check when the person comes back.",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code_challenge",
            "in": "query",
            "description": "BASE64URL(SHA256(code_verifier)).",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "code_challenge_method",
            "in": "query",
            "description": "Always `S256`.",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "S256"
              ]
            }
          },
          {
            "name": "nonce",
            "in": "query",
            "description": "Echoed in the ID token, to bind it to this sign-in.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "prompt",
            "in": "query",
            "description": "`login` to force a fresh sign-in, `consent` to show the consent screen again.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "login",
                "consent",
                "select_account"
              ]
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to `redirect_uri` with `code` and `state`, or `error` and `error_description`."
          }
        }
      }
    },
    "/api/auth/oauth2/token": {
      "post": {
        "tags": [
          "Sign in with Pinal"
        ],
        "operationId": "token",
        "summary": "Get tokens",
        "description": "Exchange an authorization code (or a refresh token) for tokens. Confidential apps authenticate with HTTP Basic (`client_id:client_secret`); public apps send `client_id` and rely on PKCE.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "grant_type"
                ],
                "properties": {
                  "grant_type": {
                    "type": "string",
                    "enum": [
                      "authorization_code",
                      "refresh_token"
                    ]
                  },
                  "code": {
                    "type": "string",
                    "description": "From the redirect (authorization_code)."
                  },
                  "redirect_uri": {
                    "type": "string",
                    "description": "Same value as in the authorize request."
                  },
                  "code_verifier": {
                    "type": "string",
                    "description": "The PKCE verifier."
                  },
                  "refresh_token": {
                    "type": "string",
                    "description": "For grant_type=refresh_token."
                  },
                  "client_id": {
                    "type": "string",
                    "description": "Public clients only; confidential clients use HTTP Basic."
                  }
                }
              },
              "example": {
                "grant_type": "authorization_code",
                "code": "Sx8Qm…",
                "redirect_uri": "https://example.com/auth/callback",
                "code_verifier": "dBjftJeZ4CVP…"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Tokens",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TokenResponse"
                },
                "example": {
                  "access_token": "eyJhbGciOi…",
                  "token_type": "Bearer",
                  "expires_in": 3600,
                  "refresh_token": "rt_9c1…",
                  "id_token": "eyJhbGciOi…",
                  "scope": "openid profile email"
                }
              }
            }
          },
          "400": {
            "description": "Invalid grant",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OAuthError"
                }
              }
            }
          }
        }
      }
    },
    "/api/auth/oauth2/userinfo": {
      "get": {
        "tags": [
          "Sign in with Pinal"
        ],
        "operationId": "userinfo",
        "summary": "Who's signed in",
        "description": "Claims about the person, limited to the scopes they granted: `sub` always; `name` and `picture` with `profile`; `email` and `email_verified` with `email`.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [
          {
            "pinal": [
              "openid"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Claims",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserInfo"
                },
                "example": {
                  "sub": "usr_2k9d",
                  "name": "Alex Rivera",
                  "email": "alex@pinal.email",
                  "email_verified": true,
                  "picture": "https://accounts.pinal.tech/avatars/usr_2k9d.png"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/auth/oauth2/revoke": {
      "post": {
        "tags": [
          "Sign in with Pinal"
        ],
        "operationId": "revoke",
        "summary": "Revoke a token",
        "description": "Revoke an access or refresh token, e.g. when someone disconnects inside your app. Revoking a refresh token also ends the access tokens issued from it.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/x-www-form-urlencoded": {
              "schema": {
                "type": "object",
                "required": [
                  "token"
                ],
                "properties": {
                  "token": {
                    "type": "string"
                  },
                  "token_type_hint": {
                    "type": "string",
                    "enum": [
                      "access_token",
                      "refresh_token"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Revoked (also returned for unknown tokens)."
          }
        }
      }
    },
    "/api/auth/oauth2/end-session": {
      "get": {
        "tags": [
          "Sign in with Pinal"
        ],
        "operationId": "endSession",
        "summary": "Sign out",
        "description": "RP-initiated logout. Ends the person's Pinal session and returns them to one of your sign-out redirect URIs.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [],
        "parameters": [
          {
            "name": "id_token_hint",
            "in": "query",
            "description": "The ID token you received at sign-in.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "client_id",
            "in": "query",
            "description": "Your client ID.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "post_logout_redirect_uri",
            "in": "query",
            "description": "One of your registered sign-out redirect URIs.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "query",
            "description": "Echoed back.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to `post_logout_redirect_uri`."
          }
        }
      }
    },
    "/api/auth/jwks": {
      "get": {
        "tags": [
          "Sign in with Pinal"
        ],
        "operationId": "jwks",
        "summary": "Signing keys",
        "description": "Public keys (JWKS) for verifying ID tokens and JWT access tokens.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Key set",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/scopes": {
      "get": {
        "tags": [
          "Developer"
        ],
        "operationId": "listScopes",
        "summary": "Scope catalog",
        "description": "Every scope a third-party app can request, grouped by service, with the wording the consent screen uses.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [],
        "responses": {
          "200": {
            "description": "Scope groups",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "groups": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ScopeGroup"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/apps/{client_id}": {
      "get": {
        "tags": [
          "Developer"
        ],
        "operationId": "getPublicApp",
        "summary": "Public app listing",
        "description": "What the consent screen shows about an app: name, icon, description, links and developer.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [],
        "parameters": [
          {
            "name": "client_id",
            "in": "path",
            "description": "The app's client ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Listing",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicApp"
                }
              }
            }
          },
          "404": {
            "description": "No such app",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/developer/apps": {
      "get": {
        "tags": [
          "Developer"
        ],
        "operationId": "listApps",
        "summary": "List your apps",
        "description": "Apps you own, newest first. Requires a token from the Developers portal (the `developer` scope is not available to third-party apps).",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [
          {
            "pinal": [
              "developer"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Your apps",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "apps": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/App"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Developer"
        ],
        "operationId": "createApp",
        "summary": "Create an app",
        "description": "Registers a new OAuth 2 client. Web apps get a client secret, returned once in this response; single-page and native apps are public clients that use PKCE.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [
          {
            "pinal": [
              "developer"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AppInput"
              },
              "example": {
                "name": "Trailhead",
                "description": "Plan hikes with friends.",
                "type": "web",
                "homepage": "https://trailhead.example",
                "redirect_uris": [
                  "https://trailhead.example/auth/callback"
                ],
                "scopes": [
                  "openid",
                  "profile",
                  "calendar.write",
                  "photos.read"
                ]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "app": {
                      "$ref": "#/components/schemas/App"
                    },
                    "client_secret": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Shown once. Null for public clients."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/developer/apps/{client_id}": {
      "get": {
        "tags": [
          "Developer"
        ],
        "operationId": "getApp",
        "summary": "Get an app",
        "description": "One of your apps.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [
          {
            "pinal": [
              "developer"
            ]
          }
        ],
        "parameters": [
          {
            "name": "client_id",
            "in": "path",
            "description": "Client ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The app",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "app": {
                      "$ref": "#/components/schemas/App"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not yours, or not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Developer"
        ],
        "operationId": "updateApp",
        "summary": "Update an app",
        "description": "Change any field except `type`. Send only what changes. `disabled: true` pauses sign-ins.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [
          {
            "pinal": [
              "developer"
            ]
          }
        ],
        "parameters": [
          {
            "name": "client_id",
            "in": "path",
            "description": "Client ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/AppInput"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "disabled": {
                        "type": "boolean"
                      }
                    }
                  }
                ]
              },
              "example": {
                "description": "Now with shared albums.",
                "scopes": [
                  "openid",
                  "profile",
                  "photos.read",
                  "photos.share"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "app": {
                      "$ref": "#/components/schemas/App"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid field",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "delete": {
        "tags": [
          "Developer"
        ],
        "operationId": "deleteApp",
        "summary": "Delete an app",
        "description": "Deletes the app, revokes every token and removes it from people's connected apps.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [
          {
            "pinal": [
              "developer"
            ]
          }
        ],
        "parameters": [
          {
            "name": "client_id",
            "in": "path",
            "description": "Client ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/api/developer/apps/{client_id}/secret": {
      "post": {
        "tags": [
          "Developer"
        ],
        "operationId": "rotateSecret",
        "summary": "Rotate the secret",
        "description": "Issues a new client secret and invalidates the old one immediately. The new secret is returned once.",
        "servers": [
          {
            "url": "https://accounts.pinal.tech",
            "description": "Pinal Accounts"
          }
        ],
        "security": [
          {
            "pinal": [
              "developer"
            ]
          }
        ],
        "parameters": [
          {
            "name": "client_id",
            "in": "path",
            "description": "Client ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "New secret",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "app": {
                      "$ref": "#/components/schemas/App"
                    },
                    "client_secret": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/mail/messages": {
      "get": {
        "tags": [
          "Mail"
        ],
        "operationId": "listMessages",
        "summary": "List messages",
        "description": "Messages in a mailbox, newest first. With only `mail.metadata`, bodies and attachments are omitted.",
        "security": [
          {
            "pinal": [
              "mail.metadata"
            ]
          }
        ],
        "parameters": [
          {
            "name": "label",
            "in": "query",
            "description": "Filter by label ID.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "inbox"
          },
          {
            "name": "q",
            "in": "query",
            "description": "Search query, same syntax as Picacho's search bar.",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "from:sam has:attachment"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page, 1–100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a previous page's `next_cursor`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of messages",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MessagePage"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Mail"
        ],
        "operationId": "sendMessage",
        "summary": "Send a message",
        "description": "Sends immediately from the person's primary address. Flagged as a sensitive action on the consent screen.",
        "security": [
          {
            "pinal": [
              "mail.send"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutgoingMessage"
              },
              "example": {
                "to": [
                  {
                    "email": "sam@example.com"
                  }
                ],
                "subject": "Trail map",
                "text": "Here's the route for Saturday."
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Queued for delivery",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/mail/messages/{id}": {
      "get": {
        "tags": [
          "Mail"
        ],
        "operationId": "getMessage",
        "summary": "Get a message",
        "description": "One message with its body and attachment list.",
        "security": [
          {
            "pinal": [
              "mail.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Message ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The message",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Mail"
        ],
        "operationId": "updateMessage",
        "summary": "Label or mark a message",
        "description": "Add or remove labels, or mark read/unread.",
        "security": [
          {
            "pinal": [
              "mail.labels"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Message ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "add_labels": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "remove_labels": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "read": {
                    "type": "boolean"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/mail/drafts": {
      "post": {
        "tags": [
          "Mail"
        ],
        "operationId": "createDraft",
        "summary": "Create a draft",
        "description": "Saves a draft the person can review and send from their mail app.",
        "security": [
          {
            "pinal": [
              "mail.compose"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OutgoingMessage"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Draft created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Message"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/mail/labels": {
      "get": {
        "tags": [
          "Mail"
        ],
        "operationId": "listLabels",
        "summary": "List labels",
        "description": "System and custom labels with unread counts.",
        "security": [
          {
            "pinal": [
              "mail.labels"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Labels",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "labels": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Label"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/contacts": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "listContacts",
        "summary": "List contacts",
        "description": "Everyone in the address book.",
        "security": [
          {
            "pinal": [
              "contacts.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Match name, email or phone.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page, 1–100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a previous page's `next_cursor`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of contacts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "contacts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Contact"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Contacts"
        ],
        "operationId": "createContact",
        "summary": "Create a contact",
        "description": "Adds someone to the address book.",
        "security": [
          {
            "pinal": [
              "contacts.write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Contact"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Contact"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/contacts/{id}": {
      "get": {
        "tags": [
          "Contacts"
        ],
        "operationId": "getContact",
        "summary": "Get a contact",
        "description": "One contact.",
        "security": [
          {
            "pinal": [
              "contacts.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Contact ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The contact",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Contact"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "delete": {
        "tags": [
          "Contacts"
        ],
        "operationId": "deleteContact",
        "summary": "Delete a contact",
        "description": "Removes the contact.",
        "security": [
          {
            "pinal": [
              "contacts.write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Contact ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/calendar/freebusy": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "freeBusy",
        "summary": "Free/busy",
        "description": "Busy blocks across all calendars, with no event details.",
        "security": [
          {
            "pinal": [
              "calendar.freebusy"
            ]
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Start (RFC 3339).",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "End (RFC 3339).",
            "required": true,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Busy blocks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "busy": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "start": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "end": {
                            "type": "string",
                            "format": "date-time"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/calendar/events": {
      "get": {
        "tags": [
          "Calendar"
        ],
        "operationId": "listEvents",
        "summary": "List events",
        "description": "Events in a time range, expanded from recurrences.",
        "security": [
          {
            "pinal": [
              "calendar.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "description": "Start (RFC 3339).",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "to",
            "in": "query",
            "description": "End (RFC 3339).",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "calendar",
            "in": "query",
            "description": "Calendar ID.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page, 1–100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a previous page's `next_cursor`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Events",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Calendar"
        ],
        "operationId": "createEvent",
        "summary": "Create an event",
        "description": "Creates an event and, if it has attendees, sends invitations from the person.",
        "security": [
          {
            "pinal": [
              "calendar.write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Event"
              },
              "example": {
                "title": "Flatiron hike",
                "start": "2026-11-28T07:00:00-07:00",
                "end": "2026-11-28T13:00:00-07:00",
                "location": "Siphon Draw Trailhead"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Event"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/passwords/autofill": {
      "post": {
        "tags": [
          "Passwords"
        ],
        "operationId": "requestAutofill",
        "summary": "Request a fill",
        "description": "Asks the person's device to fill a login for `origin`. They approve it there; you get back an encrypted item only your app's session key can open.",
        "security": [
          {
            "pinal": [
              "passwords.autofill"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "origin",
                  "public_key"
                ],
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "https://example.com"
                  },
                  "public_key": {
                    "type": "string",
                    "description": "Your ephemeral X25519 public key (base64url)."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Waiting for approval",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "request_id": {
                      "type": "string"
                    },
                    "expires_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/passwords/items": {
      "get": {
        "tags": [
          "Passwords"
        ],
        "operationId": "listItems",
        "summary": "List vault items",
        "description": "Encrypted items. Decrypting needs the person's vault key, which never leaves their devices.",
        "security": [
          {
            "pinal": [
              "passwords.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page, 1–100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a previous page's `next_cursor`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Items",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/VaultItem"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Passwords"
        ],
        "operationId": "createItem",
        "summary": "Save an item",
        "description": "Stores an item you encrypted client-side with the person's vault key.",
        "security": [
          {
            "pinal": [
              "passwords.write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/VaultItem"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VaultItem"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/notes": {
      "get": {
        "tags": [
          "Notes"
        ],
        "operationId": "listNotes",
        "summary": "List notes",
        "description": "Notes, most recently edited first.",
        "security": [
          {
            "pinal": [
              "notes.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "notebook",
            "in": "query",
            "description": "Notebook ID.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "q",
            "in": "query",
            "description": "Full-text search.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page, 1–100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a previous page's `next_cursor`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Notes",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "notes": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Note"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Notes"
        ],
        "operationId": "createNote",
        "summary": "Create a note",
        "description": "Creates a note in a notebook (the default one if omitted). Content is Markdown.",
        "security": [
          {
            "pinal": [
              "notes.write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Note"
              },
              "example": {
                "title": "Ideas",
                "content": "- Sunrise hike\n- Picnic at Lost Dutchman"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Note"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/notes/{id}": {
      "get": {
        "tags": [
          "Notes"
        ],
        "operationId": "getNote",
        "summary": "Get a note",
        "description": "One note with its content.",
        "security": [
          {
            "pinal": [
              "notes.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Note ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The note",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Note"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "patch": {
        "tags": [
          "Notes"
        ],
        "operationId": "updateNote",
        "summary": "Update a note",
        "description": "Change the title, content or notebook.",
        "security": [
          {
            "pinal": [
              "notes.write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Note ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Note"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Note"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "delete": {
        "tags": [
          "Notes"
        ],
        "operationId": "deleteNote",
        "summary": "Delete a note",
        "description": "Moves it to the trash for 30 days.",
        "security": [
          {
            "pinal": [
              "notes.write"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Note ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted."
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/notes/{id}/share": {
      "post": {
        "tags": [
          "Notes"
        ],
        "operationId": "shareNote",
        "summary": "Share a note",
        "description": "Creates a share link or invites people by email.",
        "security": [
          {
            "pinal": [
              "notes.share"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Note ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "invite": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "format": "email"
                    }
                  },
                  "link": {
                    "type": "boolean"
                  },
                  "access": {
                    "type": "string",
                    "enum": [
                      "view",
                      "edit"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shared",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "invited": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/photos": {
      "get": {
        "tags": [
          "Photos"
        ],
        "operationId": "listPhotos",
        "summary": "List photos",
        "description": "Library items, newest first, with thumbnails and metadata.",
        "security": [
          {
            "pinal": [
              "photos.read"
            ]
          }
        ],
        "parameters": [
          {
            "name": "album",
            "in": "query",
            "description": "Album ID.",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "taken_after",
            "in": "query",
            "description": "RFC 3339.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page, 1–100.",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 25
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a previous page's `next_cursor`.",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Photos",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "photos": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Photo"
                      }
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Photos"
        ],
        "operationId": "uploadPhoto",
        "summary": "Upload a photo",
        "description": "Uploads an image or video. With only `photos.upload`, the response omits other library items.",
        "security": [
          {
            "pinal": [
              "photos.upload"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "album": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Photo"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/photos/albums": {
      "get": {
        "tags": [
          "Photos"
        ],
        "operationId": "listAlbums",
        "summary": "List albums",
        "description": "Albums the app can see.",
        "security": [
          {
            "pinal": [
              "photos.read"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Albums",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "albums": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Album"
                      }
                    }
                  }
                },
                "example": {
                  "albums": [
                    {
                      "id": "alb_77b0",
                      "title": "Superstition Mountains",
                      "count": 148
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      },
      "post": {
        "tags": [
          "Photos"
        ],
        "operationId": "createAlbum",
        "summary": "Create an album",
        "description": "Creates an album, optionally with items.",
        "security": [
          {
            "pinal": [
              "photos.albums"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "title"
                ],
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "photos": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Album"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    },
    "/photos/albums/{id}/share": {
      "post": {
        "tags": [
          "Photos"
        ],
        "operationId": "shareAlbum",
        "summary": "Share an album",
        "description": "Creates a shared album link.",
        "security": [
          {
            "pinal": [
              "photos.share"
            ]
          }
        ],
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "description": "Album ID.",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "expires_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "format": "date-time"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Shared",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "url": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "pinal": {
        "type": "oauth2",
        "description": "Pinal Accounts. Scopes are listed at /docs/scopes.",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://accounts.pinal.tech/api/auth/oauth2/authorize",
            "tokenUrl": "https://accounts.pinal.tech/api/auth/oauth2/token",
            "refreshUrl": "https://accounts.pinal.tech/api/auth/oauth2/token",
            "scopes": {
              "openid": "Sign in with Pinal",
              "profile": "Profile",
              "email": "Email address",
              "offline_access": "Offline access",
              "mail.metadata": "Read message metadata",
              "mail.read": "Read mail",
              "mail.compose": "Create drafts",
              "mail.send": "Send mail",
              "mail.labels": "Manage labels",
              "mail.settings": "Mail settings",
              "contacts.read": "Read contacts",
              "contacts.write": "Manage contacts",
              "calendar.freebusy": "Free/busy",
              "calendar.read": "Read events",
              "calendar.write": "Manage events",
              "passwords.autofill": "Autofill",
              "passwords.read": "Read vault",
              "passwords.write": "Save to vault",
              "notes.read": "Read notes",
              "notes.write": "Write notes",
              "notes.share": "Share notes",
              "photos.read": "View library",
              "photos.upload": "Upload",
              "photos.albums": "Manage albums",
              "photos.share": "Share",
              "developer": "Manage your apps (Developers portal only)"
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing, expired or revoked access token.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "invalid_token",
              "error_description": "The access token expired"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The token doesn't carry the scope this operation needs.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "insufficient_scope",
              "error_description": "Requires mail.read"
            }
          }
        }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "example": "invalid_request"
          },
          "error_description": {
            "type": "string"
          },
          "field": {
            "type": "string",
            "description": "The request field at fault, when there is one."
          }
        }
      },
      "OAuthError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string",
            "enum": [
              "invalid_request",
              "invalid_client",
              "invalid_grant",
              "unauthorized_client",
              "unsupported_grant_type",
              "invalid_scope"
            ]
          },
          "error_description": {
            "type": "string"
          }
        }
      },
      "TokenResponse": {
        "type": "object",
        "required": [
          "access_token",
          "token_type",
          "expires_in"
        ],
        "properties": {
          "access_token": {
            "type": "string"
          },
          "token_type": {
            "type": "string",
            "enum": [
              "Bearer"
            ]
          },
          "expires_in": {
            "type": "integer",
            "description": "Seconds."
          },
          "refresh_token": {
            "type": "string",
            "description": "With the offline_access scope."
          },
          "id_token": {
            "type": "string",
            "description": "With the openid scope."
          },
          "scope": {
            "type": "string"
          }
        }
      },
      "UserInfo": {
        "type": "object",
        "required": [
          "sub"
        ],
        "properties": {
          "sub": {
            "type": "string",
            "description": "Stable account ID."
          },
          "name": {
            "type": "string"
          },
          "given_name": {
            "type": "string"
          },
          "family_name": {
            "type": "string"
          },
          "picture": {
            "type": "string",
            "format": "uri"
          },
          "email": {
            "type": "string",
            "format": "email"
          },
          "email_verified": {
            "type": "boolean"
          }
        }
      },
      "Scope": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "mail.read"
          },
          "title": {
            "type": "string"
          },
          "consent": {
            "type": "string",
            "description": "The line shown on the consent screen."
          },
          "description": {
            "type": "string"
          },
          "level": {
            "type": "string",
            "enum": [
              "basic",
              "sensitive",
              "restricted"
            ]
          }
        }
      },
      "ScopeGroup": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "icon": {
            "type": "string"
          },
          "blurb": {
            "type": "string"
          },
          "scopes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Scope"
            }
          }
        }
      },
      "AppInput": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 2,
            "maxLength": 48
          },
          "description": {
            "type": "string",
            "maxLength": 300
          },
          "icon": {
            "type": [
              "string",
              "null"
            ],
            "description": "https URL or a data: URL (PNG, JPEG, WebP or GIF, under 256 KB)."
          },
          "accent": {
            "type": [
              "string",
              "null"
            ],
            "pattern": "^#[0-9a-fA-F]{6}$"
          },
          "homepage": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "privacy_policy": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "terms_of_service": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "support_email": {
            "type": [
              "string",
              "null"
            ],
            "format": "email"
          },
          "type": {
            "type": "string",
            "enum": [
              "web",
              "spa",
              "native"
            ],
            "description": "Create only. web = confidential client with a secret; spa and native = public clients with PKCE."
          },
          "redirect_uris": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "post_logout_redirect_uris": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "App": {
        "type": "object",
        "properties": {
          "client_id": {
            "type": "string",
            "example": "pnl_7Hq2xV9kLmA1"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          },
          "accent": {
            "type": [
              "string",
              "null"
            ]
          },
          "homepage": {
            "type": [
              "string",
              "null"
            ]
          },
          "privacy_policy": {
            "type": [
              "string",
              "null"
            ]
          },
          "terms_of_service": {
            "type": [
              "string",
              "null"
            ]
          },
          "support_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "type": {
            "type": "string",
            "enum": [
              "web",
              "spa",
              "native"
            ]
          },
          "public": {
            "type": "boolean"
          },
          "redirect_uris": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "post_logout_redirect_uris": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "disabled": {
            "type": "boolean"
          },
          "secret_hint": {
            "type": [
              "string",
              "null"
            ],
            "description": "Last four characters of the secret."
          },
          "users": {
            "type": "integer",
            "description": "People who have connected the app."
          },
          "created_at": {
            "type": "string",
            "format": "date-time"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "PublicApp": {
        "type": "object",
        "properties": {
          "client_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "icon": {
            "type": [
              "string",
              "null"
            ]
          },
          "homepage": {
            "type": [
              "string",
              "null"
            ]
          },
          "privacy_policy": {
            "type": [
              "string",
              "null"
            ]
          },
          "terms_of_service": {
            "type": [
              "string",
              "null"
            ]
          },
          "first_party": {
            "type": "boolean"
          },
          "developer": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "name": {
                "type": "string"
              }
            }
          },
          "users": {
            "type": "integer"
          }
        }
      },
      "Address": {
        "type": "object",
        "required": [
          "email"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "email": {
            "type": "string",
            "format": "email"
          }
        }
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "msg_8f2c41"
          },
          "thread_id": {
            "type": "string"
          },
          "from": {
            "$ref": "#/components/schemas/Address"
          },
          "to": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "cc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "subject": {
            "type": "string"
          },
          "snippet": {
            "type": "string"
          },
          "text": {
            "type": "string",
            "description": "Requires mail.read."
          },
          "html": {
            "type": "string",
            "description": "Requires mail.read."
          },
          "labels": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "read": {
            "type": "boolean"
          },
          "attachments": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "filename": {
                  "type": "string"
                },
                "size": {
                  "type": "integer"
                },
                "content_type": {
                  "type": "string"
                }
              }
            }
          },
          "date": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MessagePage": {
        "type": "object",
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            }
          },
          "next_cursor": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "OutgoingMessage": {
        "type": "object",
        "required": [
          "to",
          "subject"
        ],
        "properties": {
          "to": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "cc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "bcc": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "subject": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "html": {
            "type": "string"
          },
          "in_reply_to": {
            "type": "string",
            "description": "Message ID to reply to."
          }
        }
      },
      "Label": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "inbox"
          },
          "name": {
            "type": "string"
          },
          "system": {
            "type": "boolean"
          },
          "unread": {
            "type": "integer"
          },
          "color": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "Contact": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true
          },
          "name": {
            "type": "string"
          },
          "emails": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": "string",
                  "format": "email"
                }
              }
            }
          },
          "phones": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "label": {
                  "type": "string"
                },
                "value": {
                  "type": "string"
                }
              }
            }
          },
          "organization": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "groups": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Event": {
        "type": "object",
        "required": [
          "title",
          "start",
          "end"
        ],
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true
          },
          "calendar": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "start": {
            "type": "string",
            "format": "date-time"
          },
          "end": {
            "type": "string",
            "format": "date-time"
          },
          "all_day": {
            "type": "boolean"
          },
          "location": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "attendees": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Address"
            }
          },
          "recurrence": {
            "type": [
              "string",
              "null"
            ],
            "description": "RFC 5545 RRULE."
          }
        }
      },
      "VaultItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true
          },
          "kind": {
            "type": "string",
            "enum": [
              "login",
              "card",
              "note",
              "identity"
            ]
          },
          "origins": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "ciphertext": {
            "type": "string",
            "description": "XChaCha20-Poly1305, base64url. Pinal can't read it."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "Note": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "readOnly": true,
            "example": "note_31d9aa"
          },
          "title": {
            "type": "string"
          },
          "content": {
            "type": "string",
            "description": "Markdown."
          },
          "notebook": {
            "type": "string"
          },
          "pinned": {
            "type": "boolean"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "readOnly": true
          }
        }
      },
      "Photo": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string",
            "enum": [
              "photo",
              "video"
            ]
          },
          "filename": {
            "type": "string"
          },
          "width": {
            "type": "integer"
          },
          "height": {
            "type": "integer"
          },
          "taken_at": {
            "type": "string",
            "format": "date-time"
          },
          "location": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "lat": {
                "type": "number"
              },
              "lng": {
                "type": "number"
              }
            }
          },
          "thumbnail_url": {
            "type": "string",
            "format": "uri"
          },
          "original_url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Album": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "count": {
            "type": "integer"
          },
          "cover": {
            "type": [
              "string",
              "null"
            ]
          },
          "shared": {
            "type": "boolean"
          }
        }
      }
    }
  }
}