{
  "openapi": "3.1.0",
  "info": {
    "title": "Scriben API",
    "version": "2026-08-01",
    "summary": "Read your meetings, action items and memory.",
    "description": "The Scriben API gives programmatic access to what Scriben recorded and understood: notes, summaries, action items, transcript passages and durable memory.\n\nEvery endpoint reads except two, each behind a scope chosen when the key is created: `POST /v1/imports/{source}` brings history in, and `POST /v1/notes/{ref}/share` publishes one note as a page. Every response is scoped to the account that owns the API key — no endpoint accepts an account identifier as an argument.",
    "license": {
      "name": "Proprietary",
      "url": "https://scriben.ai/terms"
    },
    "contact": {
      "name": "Scriben",
      "url": "https://docs.scriben.ai"
    }
  },
  "servers": [
    {
      "url": "https://public-api.scriben.ai",
      "description": "Production"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Send your key as `Authorization: Bearer scb_live_…`. Keys are never accepted in a query parameter: URLs end up in access logs, browser history and referrer headers."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthorized",
                  "forbidden",
                  "not_found",
                  "invalid_request",
                  "method_not_allowed",
                  "internal",
                  "rate_limited"
                ],
                "description": "Stable, machine-readable. Branch on this, not on the message."
              },
              "message": {
                "type": "string",
                "description": "Human-readable. May be reworded at any time."
              },
              "request_id": {
                "type": "string",
                "description": "Quote this in a support request."
              }
            },
            "required": [
              "code",
              "message",
              "request_id"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "NoteSummary": {
        "type": "object",
        "properties": {
          "ref": {
            "type": "string",
            "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
            "examples": [
              "n_a41f9c2b0e17"
            ]
          },
          "title": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "description": "The meeting kind, e.g. \"Client call\". Empty when none was assigned."
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "failed"
            ],
            "description": "A recording that failed to process is still returned, labelled rather than hidden."
          },
          "date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "participants": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "summary": {
            "type": "string",
            "description": "Only when requested via `include`."
          },
          "action_items": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "description": "Only when requested via `include`."
          }
        },
        "required": [
          "ref",
          "title",
          "type",
          "status",
          "date",
          "participants"
        ]
      },
      "Note": {
        "type": "object",
        "properties": {
          "ref": {
            "type": "string",
            "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
            "examples": [
              "n_a41f9c2b0e17"
            ]
          },
          "title": {
            "type": "string"
          },
          "date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "summary": {
            "type": [
              "string",
              "object"
            ],
            "description": "The text, or { withheld: true, reason } when flagged as a possible prompt injection.",
            "properties": {
              "withheld": {
                "type": "boolean"
              },
              "reason": {
                "type": "string"
              }
            }
          },
          "action_items": {
            "type": "array",
            "items": {
              "type": [
                "string",
                "object"
              ]
            }
          },
          "mentions": {
            "type": "object",
            "description": "Contact details extracted from the text so a client can render them safely.",
            "properties": {
              "urls": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "emails": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "phones": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            }
          },
          "flagged": {
            "type": "boolean"
          }
        },
        "required": [
          "ref",
          "title",
          "date"
        ]
      },
      "ActionItem": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "ai_9f2c40b18e77"
          },
          "text": {
            "type": "string"
          },
          "note_ref": {
            "type": "string",
            "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
            "examples": [
              "n_a41f9c2b0e17"
            ]
          },
          "note_title": {
            "type": "string",
            "description": "The meeting this came out of, so an item is filable on its own."
          },
          "note_type": {
            "type": "string"
          },
          "date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "text",
          "note_ref",
          "note_title",
          "note_type",
          "date"
        ]
      },
      "RecentMemory": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "The memory's own durable id."
          },
          "subject": {
            "type": "string"
          },
          "text": {
            "type": "string"
          },
          "created_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "subject",
          "text",
          "created_at"
        ]
      },
      "Memory": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "visibility": {
            "type": "string",
            "description": "The account owner's own classification."
          }
        },
        "required": [
          "text",
          "subject",
          "visibility"
        ]
      },
      "Passage": {
        "type": "object",
        "properties": {
          "note_ref": {
            "type": "string",
            "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
            "examples": [
              "n_a41f9c2b0e17"
            ]
          },
          "speaker": {
            "type": "string"
          },
          "at": {
            "type": [
              "number",
              "null"
            ],
            "description": "Seconds from the start of the recording."
          },
          "text": {
            "type": [
              "string",
              "object"
            ],
            "description": "The text, or { withheld: true, reason } when flagged as a possible prompt injection.",
            "properties": {
              "withheld": {
                "type": "boolean"
              },
              "reason": {
                "type": "string"
              }
            }
          }
        },
        "required": [
          "note_ref",
          "speaker",
          "at",
          "text"
        ]
      },
      "Person": {
        "description": "A resolved person, or an ambiguous-candidates payload when a name matches more than one. Branch on `status`.",
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "resolved",
              "ambiguous"
            ]
          }
        },
        "required": [
          "status"
        ]
      }
    }
  },
  "paths": {
    "/v1/me": {
      "get": {
        "operationId": "getMe",
        "summary": "Identify the current API key",
        "description": "Confirms a key works. The first call in every integration.",
        "responses": {
          "200": {
            "description": "The key is valid.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "key_id": {
                          "type": "string"
                        },
                        "environment": {
                          "type": "string",
                          "enum": [
                            "live",
                            "test"
                          ]
                        }
                      },
                      "required": [
                        "key_id",
                        "environment"
                      ]
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/notes": {
      "get": {
        "operationId": "listNotes",
        "summary": "List notes",
        "description": "Newest first. Returns titles, dates and participants — never a transcript. `include` adds fields already held on each note, so a caller needing summaries does not have to fetch every note individually.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "description": "Match against note titles.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "include",
            "in": "query",
            "description": "Comma-separated extra fields: `summary`, `action_items`. Unknown values are ignored.",
            "schema": {
              "type": "string",
              "example": "summary,action_items"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a previous response's `next_cursor`. Do not construct or parse one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page (1–50, default 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of notes.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/NoteSummary"
                      }
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "True when another page exists."
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as `cursor` to fetch the next page."
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "data",
                    "has_more",
                    "next_cursor",
                    "as_of"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The cursor could not be decoded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/notes/{ref}": {
      "get": {
        "operationId": "getNote",
        "summary": "Get one note",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
              "examples": [
                "n_a41f9c2b0e17"
              ]
            },
            "description": "A note ref from /v1/notes. Refs are per-account: one issued to another account resolves to 404."
          }
        ],
        "responses": {
          "200": {
            "description": "The note.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Note"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "source_notes": {
                      "type": "array",
                      "description": "The notes this answer was derived from.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ref": {
                            "type": "string",
                            "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
                            "examples": [
                              "n_a41f9c2b0e17"
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "date": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "ref",
                          "title",
                          "date"
                        ]
                      }
                    }
                  },
                  "required": [
                    "data",
                    "as_of"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/notes/{ref}/transcript": {
      "get": {
        "operationId": "searchTranscript",
        "summary": "Search a transcript",
        "description": "Returns matching passages with speaker and timestamp. A whole transcript is never returned — that is a deliberate limit, not a missing feature, so `query` is required.",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
              "examples": [
                "n_a41f9c2b0e17"
              ]
            },
            "description": "A note ref from /v1/notes. Refs are per-account: one issued to another account resolves to 404."
          },
          {
            "name": "query",
            "in": "query",
            "required": true,
            "description": "Words or phrase to find.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching passages.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Passage"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "source_notes": {
                      "type": "array",
                      "description": "The notes this answer was derived from.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ref": {
                            "type": "string",
                            "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
                            "examples": [
                              "n_a41f9c2b0e17"
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "date": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "ref",
                          "title",
                          "date"
                        ]
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`query` is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/action-items": {
      "get": {
        "operationId": "listActionItems",
        "summary": "List action items",
        "description": "Action items extracted across recent notes, each with the note it came from. Scriben does not track completion, so this returns every extracted item rather than only outstanding ones.",
        "parameters": [
          {
            "name": "person",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Only items involving this person — either the text names them, or they were in the meeting."
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "Opaque cursor from a previous response's `next_cursor`. Do not construct or parse one.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Items per page (1–50, default 20).",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of action items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/ActionItem"
                      }
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "True when another page exists."
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as `cursor` to fetch the next page."
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "data",
                    "has_more",
                    "next_cursor",
                    "as_of"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The cursor could not be decoded.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/memories/recent": {
      "get": {
        "operationId": "listRecentMemories",
        "summary": "The newest memories, newest first",
        "description": "For a consumer that has to notice what is NEW rather than answer a question. Unlike `/v1/memories` this needs no query, orders by time, and carries a durable `id` and `created_at` so the same row is recognisable on a later call. Not paginated: the store caps this read, so `has_more` is always false and there is never a cursor.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 25,
              "default": 25
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The newest memories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/RecentMemory"
                      }
                    },
                    "has_more": {
                      "type": "boolean",
                      "description": "True when another page exists."
                    },
                    "next_cursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as `cursor` to fetch the next page."
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    }
                  },
                  "required": [
                    "data",
                    "has_more",
                    "next_cursor",
                    "as_of"
                  ]
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/memories": {
      "get": {
        "operationId": "listMemories",
        "summary": "Search durable memories",
        "description": "Respects the account owner's own private/team visibility settings.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching memories.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Memory"
                      }
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "`query` is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/people": {
      "get": {
        "operationId": "getPerson",
        "summary": "What the account knows about a person",
        "description": "If a name matches more than one person, this returns candidates with `status: \"ambiguous\"` and a 200 — rather than guessing. Two people sharing a first name is normal; blending them is not.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Name or email address."
          },
          {
            "name": "ref",
            "in": "query",
            "schema": {
              "type": "string"
            },
            "description": "Exact entity ref, to resolve a previous ambiguous result."
          }
        ],
        "responses": {
          "200": {
            "description": "A resolved person, or candidates.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Person"
                    },
                    "as_of": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "source_notes": {
                      "type": "array",
                      "description": "The notes this answer was derived from.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "ref": {
                            "type": "string",
                            "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
                            "examples": [
                              "n_a41f9c2b0e17"
                            ]
                          },
                          "title": {
                            "type": "string"
                          },
                          "date": {
                            "type": [
                              "string",
                              "null"
                            ]
                          }
                        },
                        "required": [
                          "ref",
                          "title",
                          "date"
                        ]
                      }
                    }
                  },
                  "required": [
                    "data",
                    "as_of"
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Provide `name` or `ref`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/imports/{source}": {
      "post": {
        "operationId": "importNotes",
        "summary": "Import your own history from another tool",
        "description": "The only endpoint in this API that writes. It exists so a user leaving Granola, Plaud, Limitless, Otter or Fireflies can bring their own history with them.\n\nRequires a key carrying the `import` scope, which must be chosen when the key is created — read-only keys cannot be upgraded in place.\n\n`Idempotency-Key` is required, not optional: a retried import that duplicated a history would be worse than one that failed. Replaying a key returns the original result.\n\nUse `?dry_run=1` to see exactly what would be imported without writing anything.",
        "parameters": [
          {
            "name": "source",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "granola",
                "plaud",
                "limitless",
                "otter",
                "fireflies",
                "generic"
              ]
            },
            "description": "Where the data came from. Every imported note records this."
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "A value you choose. Retrying with the same one returns the first result rather than importing again."
          },
          {
            "name": "dry_run",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "1",
                "true"
              ]
            },
            "description": "Validate and report what would happen, writing nothing."
          }
        ],
        "requestBody": {
          "required": true,
          "description": "The export from the source tool: an array of its items, or the object that wraps one.",
          "content": {
            "application/json": {
              "schema": {
                "type": [
                  "array",
                  "object"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "What arrived, and what did not.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "import_id": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "source": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "staged"
                      ],
                      "description": "Imports are staged for review, then added from the app. Nothing appears in your notes until you confirm it."
                    },
                    "dry_run": {
                      "type": "boolean"
                    },
                    "imported": {
                      "type": "integer"
                    },
                    "accepted": {
                      "type": "integer"
                    },
                    "rejected": {
                      "type": "integer"
                    },
                    "rejected_rows": {
                      "type": "array",
                      "description": "Rows that did not come across, each with a reason. Never silently dropped.",
                      "items": {
                        "type": "object",
                        "properties": {
                          "index": {
                            "type": "integer"
                          },
                          "external_id": {
                            "type": "string"
                          },
                          "reason": {
                            "type": "string",
                            "enum": [
                              "not_an_object",
                              "no_content",
                              "duplicate_in_request"
                            ]
                          }
                        }
                      }
                    },
                    "already_present": {
                      "type": "integer",
                      "description": "Matched an earlier import and was not duplicated."
                    },
                    "people": {
                      "type": "integer"
                    },
                    "action_items": {
                      "type": "integer"
                    },
                    "undated": {
                      "type": "integer",
                      "description": "Accepted, but with no parseable date. Never defaulted to today."
                    },
                    "range": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "from": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "to": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        }
                      }
                    },
                    "replayed": {
                      "type": "boolean",
                      "description": "This Idempotency-Key was already used; the original result is returned."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Missing `Idempotency-Key`, or a payload that is not a list of items.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "This key does not carry the `import` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/notes/{ref}/share": {
      "post": {
        "operationId": "createShare",
        "summary": "Publish a note as a page anyone can open",
        "description": "Mints a public URL for one note: title, date, summary and action items, rendered as a self-contained page that opens without a Scriben account. It is what an automation actually needs — the people reading a CRM record or a ticket are usually not Scriben users, and a link is not the same thing as a wall of pasted text.\n\nThe page NEVER contains a transcript. That is the same boundary the rest of this API keeps by returning transcripts only as query-matched passages.\n\nRequires a key carrying the `share` scope, chosen when the key is created. It is deliberately separate from `import`: bringing history in is private to the account, publishing is not, and a key trusted with one is not automatically trusted with the other.\n\nNot idempotent — each call mints a new link. A duplicate is a second URL to the same recap which expires on its own, so requiring an `Idempotency-Key` would cost callers more than the duplicate does.",
        "parameters": [
          {
            "name": "ref",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "description": "Opaque per-user note reference, e.g. n_a41f9c2b0e17.",
              "examples": [
                "n_a41f9c2b0e17"
              ]
            },
            "description": "A note ref from /v1/notes. Refs are per-account: one issued to another account resolves to 404."
          }
        ],
        "responses": {
          "200": {
            "description": "The link, and when it stops working.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "url": {
                          "type": "string",
                          "description": "Absolute where the service has a public origin configured."
                        },
                        "token": {
                          "type": "string",
                          "description": "The share id, also the last path segment of `url`."
                        },
                        "title": {
                          "type": "string"
                        },
                        "expires_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time",
                          "description": "Shares expire. After this the URL returns 404."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The note has no summary or action items to publish — including when its content was withheld as a suspected prompt injection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "This key does not carry the `share` scope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "No such resource for this account.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "500": {
            "description": "Something went wrong on our end. Quote `request_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/imports": {
      "get": {
        "operationId": "listImports",
        "summary": "List past imports",
        "responses": {
          "200": {
            "description": "Previous imports, newest first.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "The key is missing, malformed, revoked or expired. All four are reported identically.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests for this account. Retry after `Retry-After` seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "tags": [
    {
      "name": "Read",
      "description": "Every endpoint in this API is read-only."
    }
  ]
}