{
  "openapi": "3.1.0",
  "info": {
    "title": "Robono Linked Apps API",
    "version": "1.0.0-preview",
    "description": "User-authorized companion apps. Direct integrations supply app identity without developer registration. Tokens are distinct from Robono phone sessions.",
    "license": {
      "name": "Proprietary",
      "url": "https://robono.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://vzoqxavqacydtwypjsrd.supabase.co/functions/v1",
      "description": "Robono linked-app service"
    }
  ],
  "tags": [
    {
      "name": "Linked apps",
      "description": "Consent, scoped messaging, durable sync and disconnection"
    }
  ],
  "paths": {
    "/linked-app-pair": {
      "post": {
        "operationId": "startLinkedAppPairing",
        "summary": "Create a five-minute code for the user to enter in Robono",
        "security": [],
        "tags": [
          "Linked apps"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PairStart"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Pairing"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or expired request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; back off before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Operation rejected; inspect error code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/linked-app-authorize": {
      "post": {
        "operationId": "authorizeLinkedApp",
        "summary": "Start a user approval request",
        "security": [],
        "tags": [
          "Linked apps"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Authorize"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Authorization"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or expired request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; back off before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Operation rejected; inspect error code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/linked-app-token": {
      "post": {
        "operationId": "exchangeLinkedAppToken",
        "summary": "Exchange an approved code or rotate a refresh token",
        "security": [],
        "tags": [
          "Linked apps"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/CodeExchange"
                  },
                  {
                    "$ref": "#/components/schemas/Refresh"
                  },
                  {
                    "$ref": "#/components/schemas/PairExchange"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tokens"
                }
              }
            }
          },
          "400": {
            "description": "Invalid or expired request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "Renewal request ID belongs to another generation, or its result was superseded. Reload the owner’s committed credentials; do not overwrite them with an older pair.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; back off before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Operation rejected; inspect error code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "description": "For refresh requests, persist a request_id before sending and retry the same ID with the same source refresh credential after a lost response, app restart, or failed credential save. Recovery returns the original pair without extending expiry. Coordinate one renewal owner per grant. Published SDK 0.1.0-preview.4 does not yet implement this recovery contract. Initial pairing and authorization-code exchange are not recoverable through request_id."
      }
    },
    "/linked-app-manage": {
      "post": {
        "operationId": "manageLinkedApps",
        "summary": "Robono phone only: approve, deny, inspect and revoke grants",
        "security": [
          {
            "phoneBearer": []
          }
        ],
        "tags": [
          "Linked apps"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "action": {
                        "const": "pair_preview"
                      },
                      "user_code": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "user_code"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "action": {
                        "enum": [
                          "pair_approve",
                          "pair_deny"
                        ]
                      },
                      "pairing_id": {
                        "type": "string",
                        "format": "uuid"
                      },
                      "decision_token": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "action",
                      "pairing_id",
                      "decision_token"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "action": {
                        "const": "list"
                      }
                    },
                    "required": [
                      "action"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "action": {
                        "const": "revoke"
                      },
                      "grant_id": {
                        "type": "string",
                        "format": "uuid"
                      }
                    },
                    "required": [
                      "action",
                      "grant_id"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "action": {
                        "enum": [
                          "preview",
                          "approve",
                          "deny"
                        ]
                      },
                      "request_id": {
                        "type": "string",
                        "format": "uuid"
                      }
                    },
                    "required": [
                      "action",
                      "request_id"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "pairing_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "decision_token": {
                          "type": "string"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "account:read",
                              "messages:read",
                              "messages:send",
                              "receipts:write"
                            ]
                          }
                        },
                        "expires_at": {
                          "type": "string"
                        },
                        "app": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            },
                            "developer_name": {
                              "type": "string"
                            },
                            "website_url": {
                              "type": "string"
                            },
                            "privacy_url": {
                              "type": "string"
                            },
                            "direct_client": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "name",
                            "developer_name",
                            "website_url",
                            "privacy_url"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "required": [
                        "pairing_id",
                        "decision_token",
                        "scopes",
                        "expires_at",
                        "app"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "approved": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "approved"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "apps": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "scopes": {
                                "type": "array",
                                "items": {
                                  "type": "string",
                                  "enum": [
                                    "account:read",
                                    "messages:read",
                                    "messages:send",
                                    "receipts:write"
                                  ]
                                }
                              },
                              "created_at": {
                                "type": "string"
                              },
                              "expires_at": {
                                "type": "string"
                              },
                              "last_used_at": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              },
                              "linked_apps": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "developer_name": {
                                    "type": "string"
                                  },
                                  "website_url": {
                                    "type": "string"
                                  },
                                  "privacy_url": {
                                    "type": "string"
                                  },
                                  "direct_client": {
                                    "type": "boolean"
                                  },
                                  "status": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "name",
                                  "developer_name",
                                  "website_url",
                                  "privacy_url"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "id",
                              "scopes",
                              "created_at",
                              "expires_at",
                              "last_used_at",
                              "linked_apps"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "apps"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "request_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "account:read",
                              "messages:read",
                              "messages:send",
                              "receipts:write"
                            ]
                          }
                        },
                        "expires_at": {
                          "type": "string"
                        },
                        "app": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "name": {
                              "type": "string"
                            },
                            "developer_name": {
                              "type": "string"
                            },
                            "website_url": {
                              "type": "string"
                            },
                            "privacy_url": {
                              "type": "string"
                            },
                            "direct_client": {
                              "type": "boolean"
                            }
                          },
                          "required": [
                            "id",
                            "name",
                            "developer_name",
                            "website_url",
                            "privacy_url"
                          ],
                          "additionalProperties": false
                        }
                      },
                      "required": [
                        "request_id",
                        "scopes",
                        "expires_at",
                        "app"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "redirect_url": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "redirect_url"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "revoked": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "revoked"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid or expired request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; back off before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Operation rejected; inspect error code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/linked-app-stream": {
      "get": {
        "operationId": "streamLinkedAppEvents",
        "summary": "Open an authenticated WebSocket event stream",
        "description": "Connect with WSS, no query parameters. Authenticate in the first JSON frame within 10 seconds. See the integration guide for ready/page/ack/ping/reconnect protocol. Requires messages:read; no webhook endpoint is supported.",
        "externalDocs": {
          "url": "https://robono.com/linked-app-resources/integration-guide.txt"
        },
        "responses": {
          "101": {
            "description": "WebSocket upgraded; account authentication follows in the first frame"
          },
          "426": {
            "description": "WebSocket upgrade required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/linked-app-api": {
      "post": {
        "operationId": "callLinkedApp",
        "summary": "Versioned scoped operations",
        "security": [
          {
            "linkedBearer": []
          }
        ],
        "tags": [
          "Linked apps"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "account.get"
                      },
                      "input": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "conversations.list"
                      },
                      "input": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "messages.list"
                      },
                      "input": {
                        "type": "object",
                        "properties": {
                          "conversationId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "before": {
                            "type": "string"
                          },
                          "beforeId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "limit": {
                            "type": "integer",
                            "minimum": 1,
                            "maximum": 100
                          },
                          "includeVoicePlaybackUrls": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "conversationId"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "messages.get"
                      },
                      "input": {
                        "type": "object",
                        "properties": {
                          "conversationId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "messageId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "after": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "conversationId",
                          "messageId"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "messages.send"
                      },
                      "input": {
                        "type": "object",
                        "properties": {
                          "conversationId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "messageKind": {
                            "enum": [
                              "text",
                              "voice",
                              "image",
                              "video",
                              "document"
                            ]
                          },
                          "clientMessageId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "textBody": {
                            "type": "string"
                          },
                          "mediaObjectId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "replyToMessageId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "inputSource": {
                            "const": "external"
                          }
                        },
                        "required": [
                          "conversationId",
                          "messageKind",
                          "clientMessageId"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "media.upload"
                      },
                      "input": {
                        "type": "object",
                        "properties": {
                          "conversationId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "mediaKind": {
                            "enum": [
                              "voice",
                              "image",
                              "video",
                              "document"
                            ]
                          },
                          "mimeType": {
                            "type": "string"
                          },
                          "sizeBytes": {
                            "type": "integer",
                            "minimum": 1
                          },
                          "fileName": {
                            "type": "string"
                          },
                          "durationMs": {
                            "type": "integer"
                          },
                          "waveform": {
                            "type": "array",
                            "items": {
                              "type": "number"
                            }
                          }
                        },
                        "required": [
                          "conversationId",
                          "mediaKind",
                          "mimeType",
                          "sizeBytes"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "media.download"
                      },
                      "input": {
                        "type": "object",
                        "properties": {
                          "messageId": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "required": [
                          "messageId"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "receipts.update"
                      },
                      "input": {
                        "type": "object",
                        "properties": {
                          "messageId": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "heard": {
                            "type": "boolean"
                          },
                          "deliveredOnly": {
                            "type": "boolean"
                          }
                        },
                        "required": [
                          "messageId"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "events.poll"
                      },
                      "input": {
                        "type": "object",
                        "properties": {
                          "cursor": {
                            "anyOf": [
                              {
                                "type": "string",
                                "pattern": "^(0|[1-9][0-9]{0,17})$"
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        },
                        "required": [
                          "cursor"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  },
                  {
                    "type": "object",
                    "properties": {
                      "version": {
                        "const": 1
                      },
                      "operation": {
                        "const": "connection.revoke"
                      },
                      "input": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "required": [
                      "version",
                      "operation",
                      "input"
                    ],
                    "additionalProperties": false
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful request",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "properties": {
                        "account": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string",
                              "format": "uuid"
                            },
                            "display_name": {
                              "anyOf": [
                                {
                                  "type": "string"
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "phone": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "id",
                            "display_name",
                            "phone"
                          ],
                          "additionalProperties": false
                        },
                        "grant_id": {
                          "type": "string",
                          "format": "uuid"
                        },
                        "scopes": {
                          "type": "array",
                          "items": {
                            "type": "string",
                            "enum": [
                              "account:read",
                              "messages:read",
                              "messages:send",
                              "receipts:write"
                            ]
                          }
                        }
                      },
                      "required": [
                        "account",
                        "grant_id",
                        "scopes"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "conversations": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Conversation"
                          }
                        },
                        "messages": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Message"
                          }
                        },
                        "deletedConversations": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "conversationId": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "historyClearedAt": {
                                "anyOf": [
                                  {
                                    "type": "string"
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              }
                            },
                            "required": [
                              "conversationId",
                              "historyClearedAt"
                            ],
                            "additionalProperties": false
                          }
                        }
                      },
                      "required": [
                        "conversations",
                        "messages",
                        "deletedConversations"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "messages": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Message"
                          }
                        },
                        "has_more": {
                          "type": "boolean"
                        },
                        "next_before": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "next_before_id": {
                          "anyOf": [
                            {
                              "type": "string",
                              "format": "uuid"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "messages",
                        "has_more",
                        "next_before",
                        "next_before_id"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "message": {
                          "$ref": "#/components/schemas/Message"
                        },
                        "messages": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Message"
                          }
                        }
                      },
                      "required": [
                        "message",
                        "messages"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "message": {
                          "$ref": "#/components/schemas/Message"
                        }
                      },
                      "required": [
                        "message"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "receipts": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Receipt"
                          }
                        }
                      },
                      "required": [
                        "receipts"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "signedUrl": {
                          "type": "string"
                        },
                        "expiresIn": {
                          "type": "integer"
                        }
                      },
                      "required": [
                        "signedUrl",
                        "expiresIn"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "object",
                      "properties": {
                        "media": {
                          "$ref": "#/components/schemas/Media"
                        },
                        "signedUrl": {
                          "type": "string"
                        },
                        "token": {
                          "type": "string"
                        },
                        "path": {
                          "type": "string"
                        },
                        "thumbnailUpload": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "signedUrl": {
                                  "type": "string"
                                },
                                "token": {
                                  "type": "string"
                                },
                                "path": {
                                  "type": "string"
                                }
                              },
                              "required": [
                                "signedUrl",
                                "token",
                                "path"
                              ],
                              "additionalProperties": false
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      },
                      "required": [
                        "media",
                        "signedUrl",
                        "token",
                        "path",
                        "thumbnailUpload"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "$ref": "#/components/schemas/Events"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "revoked": {
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "revoked"
                      ],
                      "additionalProperties": false
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Invalid or expired request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Missing, revoked or expired credential",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Insufficient permission",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit; back off before retrying",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Disabled or temporarily unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Operation rejected; inspect error code",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "linkedBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Scoped rla_ credential. Never a Robono phone session."
      },
      "phoneBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Robono primary phone session. Only the Robono app can approve grants."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "reason": {
            "type": "string",
            "description": "Optional detail for credential or connection failure. Examples: access_token_expired, access_token_replaced, connection_revoked, connection_expired, connection_unavailable, refresh_token_expired, refresh_token_invalid, refresh_token_reused, refresh_recovery_expired, refresh_request_conflict, refresh_result_superseded. HTTP 503 temporarily_unavailable means preserve credentials and retry with backoff."
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      },
      "AppIdentity": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 100
          },
          "developerName": {
            "type": "string",
            "minLength": 1,
            "maxLength": 150
          },
          "websiteUrl": {
            "type": "string",
            "format": "uri"
          },
          "privacyUrl": {
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "name",
          "developerName",
          "websiteUrl",
          "privacyUrl"
        ],
        "additionalProperties": false
      },
      "PairStart": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "app": {
                "$ref": "#/components/schemas/AppIdentity"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "account:read",
                    "messages:read",
                    "messages:send",
                    "receipts:write"
                  ]
                },
                "minItems": 1
              },
              "code_challenge": {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{43}$"
              },
              "code_challenge_method": {
                "const": "S256"
              }
            },
            "required": [
              "app",
              "scopes",
              "code_challenge",
              "code_challenge_method"
            ],
            "additionalProperties": false
          },
          {
            "type": "object",
            "properties": {
              "client_id": {
                "type": "string",
                "format": "uuid"
              },
              "scopes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "account:read",
                    "messages:read",
                    "messages:send",
                    "receipts:write"
                  ]
                },
                "minItems": 1
              },
              "code_challenge": {
                "type": "string",
                "pattern": "^[A-Za-z0-9_-]{43}$"
              },
              "code_challenge_method": {
                "const": "S256"
              }
            },
            "required": [
              "client_id",
              "scopes",
              "code_challenge",
              "code_challenge_method"
            ],
            "additionalProperties": false
          }
        ]
      },
      "Pairing": {
        "type": "object",
        "properties": {
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "user_code": {
            "type": "string"
          },
          "device_code": {
            "type": "string"
          },
          "expires_in": {
            "type": "integer"
          },
          "expires_at": {
            "type": "string"
          },
          "interval": {
            "type": "integer"
          },
          "verification_uri": {
            "type": "string"
          },
          "verification_app_uri": {
            "type": "string"
          }
        },
        "required": [
          "client_id",
          "user_code",
          "device_code",
          "expires_in",
          "expires_at",
          "interval",
          "verification_uri",
          "verification_app_uri"
        ],
        "additionalProperties": false
      },
      "PairExchange": {
        "type": "object",
        "properties": {
          "grant_type": {
            "const": "urn:ietf:params:oauth:grant-type:device_code"
          },
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "device_code": {
            "type": "string"
          },
          "code_verifier": {
            "type": "string",
            "minLength": 43,
            "maxLength": 128
          }
        },
        "required": [
          "grant_type",
          "client_id",
          "device_code",
          "code_verifier"
        ],
        "additionalProperties": false
      },
      "Authorize": {
        "type": "object",
        "properties": {
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "redirect_uri": {
            "type": "string",
            "format": "uri"
          },
          "state": {
            "type": "string",
            "minLength": 32,
            "maxLength": 256
          },
          "scopes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "account:read",
                "messages:read",
                "messages:send",
                "receipts:write"
              ]
            },
            "minItems": 1
          },
          "code_challenge": {
            "type": "string",
            "pattern": "^[A-Za-z0-9_-]{43}$"
          },
          "code_challenge_method": {
            "const": "S256"
          }
        },
        "required": [
          "client_id",
          "redirect_uri",
          "state",
          "scopes",
          "code_challenge",
          "code_challenge_method"
        ],
        "additionalProperties": false
      },
      "Authorization": {
        "type": "object",
        "properties": {
          "request_id": {
            "type": "string",
            "format": "uuid"
          },
          "authorization_url": {
            "type": "string",
            "format": "uri"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "request_id",
          "authorization_url",
          "expires_at"
        ],
        "additionalProperties": false
      },
      "CodeExchange": {
        "type": "object",
        "properties": {
          "grant_type": {
            "const": "authorization_code"
          },
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "redirect_uri": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "code_verifier": {
            "type": "string",
            "minLength": 43,
            "maxLength": 128
          }
        },
        "required": [
          "grant_type",
          "client_id",
          "redirect_uri",
          "code",
          "code_verifier"
        ],
        "additionalProperties": false
      },
      "Refresh": {
        "type": "object",
        "properties": {
          "grant_type": {
            "const": "refresh_token"
          },
          "client_id": {
            "type": "string",
            "format": "uuid"
          },
          "refresh_token": {
            "type": "string"
          },
          "request_id": {
            "type": "string",
            "format": "uuid",
            "description": "Optional renewal-attempt UUID. Persist before sending; reuse with the same source refresh credential on retries. A new renewal generation needs a fresh ID. Same-attempt recovery lasts up to 24 hours while the connection remains authorized and its replacement is not superseded. A different attempt using a spent credential still revokes the grant."
          }
        },
        "required": [
          "grant_type",
          "client_id",
          "refresh_token"
        ],
        "additionalProperties": false
      },
      "Tokens": {
        "type": "object",
        "properties": {
          "access_token": {
            "type": "string"
          },
          "refresh_token": {
            "type": "string"
          },
          "token_type": {
            "const": "Bearer"
          },
          "expires_in": {
            "type": "integer",
            "minimum": 0,
            "description": "Remaining access lifetime in seconds. May be zero on late renewal recovery; persist the recovered pair and renew its refresh credential using a new request ID."
          },
          "refresh_expires_at": {
            "type": "string"
          },
          "grant_id": {
            "type": "string",
            "format": "uuid"
          },
          "scope": {
            "type": "string"
          },
          "access_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Original access expiry; included for request-ID renewals and not extended by retries."
          },
          "recovery_expires_at": {
            "type": "string",
            "format": "date-time",
            "description": "Deadline for recovering this renewal result. Included for request-ID renewals; also subject to revocation or supersession."
          }
        },
        "required": [
          "access_token",
          "refresh_token",
          "token_type",
          "expires_in",
          "refresh_expires_at",
          "grant_id",
          "scope"
        ],
        "additionalProperties": false
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "type": {
            "enum": [
              "messages.changed",
              "receipts.changed",
              "conversations.changed"
            ]
          },
          "conversation_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "message_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "conversation_id",
          "message_id",
          "created_at"
        ],
        "additionalProperties": false
      },
      "Events": {
        "type": "object",
        "properties": {
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Event"
            }
          },
          "cursor": {
            "type": "string"
          },
          "has_more": {
            "type": "boolean"
          },
          "resync_required": {
            "type": "boolean"
          }
        },
        "required": [
          "events",
          "cursor",
          "has_more"
        ],
        "additionalProperties": false
      },
      "Receipt": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "recipient_user_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "child_app_connection_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "delivered_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "seen_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "read_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "heard_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "Media": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "media_kind": {
            "type": "string"
          },
          "mime_type": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "file_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "duration_ms": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "width": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "height": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "waveform": {
            "anyOf": [
              {
                "type": "array",
                "items": {
                  "type": "number"
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "upload_state": {
            "type": "string"
          },
          "server_expires_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "deleted_from_storage_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "signed_url": {
            "type": "string"
          },
          "signed_url_expires_at": {
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "additionalProperties": false
      },
      "Message": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "conversation_id": {
            "type": "string",
            "format": "uuid"
          },
          "sender_kind": {
            "type": "string"
          },
          "sender_user_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "child_app_connection_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "client_message_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "message_kind": {
            "enum": [
              "text",
              "voice",
              "image",
              "video",
              "document"
            ]
          },
          "text_body": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "media_object_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string"
          },
          "server_expires_at": {
            "type": "string"
          },
          "active_in_walkie_talkie": {
            "type": "boolean"
          },
          "reply_to_message_id": {
            "anyOf": [
              {
                "type": "string",
                "format": "uuid"
              },
              {
                "type": "null"
              }
            ]
          },
          "attachment_batch_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "attachment_batch_index": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "attachment_batch_count": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "local_only": {
            "type": "boolean"
          },
          "local_send_state": {
            "type": "string"
          },
          "media_objects": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Media"
              },
              {
                "type": "null"
              }
            ]
          },
          "message_receipts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Receipt"
            }
          },
          "message_reactions": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "user_id": {
                  "type": "string",
                  "format": "uuid"
                },
                "emoji": {
                  "type": "string"
                },
                "created_at": {
                  "type": "string"
                },
                "updated_at": {
                  "type": "string"
                }
              },
              "required": [],
              "additionalProperties": false
            }
          },
          "message_speech_artifacts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "artifact_kind": {
                  "type": "string"
                },
                "language_code": {
                  "type": "string"
                },
                "text_body": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "status": {
                  "type": "string"
                },
                "created_at": {
                  "type": "string"
                },
                "media_objects": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/Media"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "media_objects"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "id",
          "conversation_id",
          "message_kind",
          "created_at",
          "media_objects",
          "message_receipts",
          "message_reactions",
          "message_speech_artifacts"
        ],
        "additionalProperties": false
      },
      "Conversation": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "kind": {
            "type": "string"
          },
          "title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "mode": {
            "enum": [
              "history",
              "walkie_talkie"
            ]
          },
          "history_enabled_at": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "created_at": {
            "type": "string"
          },
          "updated_at": {
            "type": "string"
          },
          "unread_count": {
            "type": "integer"
          },
          "blocked_by_you": {
            "type": "boolean"
          },
          "user_preferences": {
            "type": "object",
            "properties": {
              "muted_at": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "blurred_at": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "history_cleared_at": {
                "anyOf": [
                  {
                    "type": "string"
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "text_translation_mode": {
                "type": "string"
              },
              "voice_translation_mode": {
                "type": "string"
              }
            },
            "required": [],
            "additionalProperties": false
          },
          "conversation_members": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "member_kind": {
                  "type": "string"
                },
                "user_id": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uuid"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "child_app_connection_id": {
                  "anyOf": [
                    {
                      "type": "string",
                      "format": "uuid"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "left_at": {
                  "anyOf": [
                    {
                      "type": "string"
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "app_users": {
                  "type": "object",
                  "properties": {
                    "display_name": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "phone_e164": {
                      "type": "string"
                    },
                    "avatar_url": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "deleted_at": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  },
                  "required": [],
                  "additionalProperties": false
                },
                "child_app_connections": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "child_original_name": {
                          "type": "string"
                        },
                        "status": {
                          "type": "string"
                        },
                        "disconnected_at": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "external_account_deleted_at": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "external_avatar_url": {
                          "anyOf": [
                            {
                              "type": "string"
                            },
                            {
                              "type": "null"
                            }
                          ]
                        },
                        "capabilities": {
                          "type": "object",
                          "additionalProperties": true,
                          "description": "Network capabilities as supplied by Robono. Enforced on every send."
                        },
                        "monitoring_disclosure": {},
                        "child_apps": {
                          "type": "object",
                          "properties": {
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [],
                          "additionalProperties": false
                        }
                      },
                      "required": [
                        "child_apps"
                      ],
                      "additionalProperties": false
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              },
              "required": [
                "app_users",
                "child_app_connections"
              ],
              "additionalProperties": false
            }
          }
        },
        "required": [
          "id",
          "blocked_by_you",
          "user_preferences",
          "conversation_members"
        ],
        "additionalProperties": false
      }
    }
  }
}
