{
"openapi": "3.1.0",
"info": {
"title": "Signatoro signature API",
"version": "1.0.0",
"summary": "Fetch the saved email signature of a person, or of one of their AI assistants or their company's AI agents, to append to an email you are about to send.",
"description": "Fetch the signature on every send and append it after the body: `html` into the text/html part, `text` into the text/plain part. Do not paste it into a mail client compose window, restyle it or cache it. For the sender's own details anywhere in the email, use only the values in `sender`; leave out what is missing."
},
"externalDocs": {
"description": "Give your signature to an AI agent",
"url": "https://signatoro.com/docs/install-signature/agent"
},
"servers": [
{
"url": "https://signatoro.com"
}
],
"security": [
{
"apiKey": []
}
],
"paths": {
"/api/v1/signature": {
"get": {
"operationId": "getSignature",
"summary": "Get the signature to append to an email",
"description": "Returns the signature as HTML and plain text, the sender's details as structured facts, and the rules for appending it. Never cacheable (`cache-control: no-store`). A key minted for an AI assistant or agent always returns that one's signature.",
"parameters": [
{
"name": "mode",
"in": "query",
"required": false,
"description": "`full` (the default): phone, email, every link and the picture. `short`: name, role line and one link, no picture, for cold outreach. Any other value is `full`.",
"schema": {
"type": "string",
"enum": [
"full",
"short"
],
"default": "full"
}
},
{
"name": "signature",
"in": "query",
"required": false,
"description": "Which signature: `me` (the default, the key owner's own) or one of their AI assistants or company AI agents, by id or name. A key bound to one accepts only its id or name.",
"schema": {
"type": "string",
"default": "me"
}
}
],
"responses": {
"200": {
"description": "The signature to append.",
"headers": {
"cache-control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SignatureResponse"
},
"examples": {
"own": {
"summary": "A person's own signature",
"value": {
"html": "",
"text": "Maya Okafor\nHead of Operations, Northwind Supply\n+1 (555) 010-0199",
"sender": {
"name": "Maya Okafor",
"title": "Head of Operations",
"company": "Northwind Supply",
"email": "maya@northwind.example",
"phone": {
"display": "+1 (555) 010-0199",
"e164": "+15550100199"
},
"website": "https://northwind.example",
"bookingUrl": "https://calendly.com/maya"
},
"signature": {
"kind": "me",
"name": "Maya Okafor"
},
"mode": "full",
"tier": "company",
"usage": "Append, do not replace: put html as-is into the text/html part of the message and text into the text/plain part, after the body and a blank line. ...",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
},
"agent": {
"summary": "An AI agent's signature",
"value": {
"html": "",
"text": "Ada\nScheduling assistant, Northwind Supply\nSent by Ada, AI assistant to Maya Okafor, Northwind Supply",
"sender": {
"name": "Ada",
"title": "Scheduling assistant",
"company": "Northwind Supply",
"website": "https://northwind.example",
"actsFor": {
"name": "Maya Okafor",
"company": "Northwind Supply"
}
},
"signature": {
"kind": "agent",
"id": "8c1e0f52-4a8e-4f0e-9d3b-2f1c6a7e5b10",
"name": "Ada"
},
"mode": "full",
"tier": "company",
"usage": "Append, do not replace: put html as-is into the text/html part of the message and text into the text/plain part, after the body and a blank line. ... Keep the disclosure line; it is part of the signature.",
"docs": "https://signatoro.com/docs/install-signature/agent",
"agent": {
"id": "8c1e0f52-4a8e-4f0e-9d3b-2f1c6a7e5b10",
"name": "Ada",
"owner": "person",
"signsAs": "agent",
"actsFor": {
"name": "Maya Okafor",
"company": "Northwind Supply"
},
"disclosure": {
"preset": "assistant_to_person",
"line": "Sent by Ada, AI assistant to Maya Okafor, Northwind Supply",
"label": "This email was written and sent by Ada, an AI assistant, on behalf of Maya Okafor.",
"lockedByCompany": false,
"about": "https://signatoro.com/email-signature-compliance/ai-email-disclosure"
}
}
}
}
}
}
}
},
"400": {
"description": "`unknown_signature`: `signature` named nothing the key may use; pick one from `choices`. `signature_locked`: a key bound to an agent asked for another signature.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"error": {
"enum": [
"unknown_signature",
"signature_locked"
]
}
}
}
]
},
"example": {
"error": "unknown_signature",
"message": "signature must be one of: \"me\" (your own signature), \"Ada\" (id 8c1e0f52-4a8e-4f0e-9d3b-2f1c6a7e5b10).",
"choices": [
"me",
{
"id": "8c1e0f52-4a8e-4f0e-9d3b-2f1c6a7e5b10",
"name": "Ada"
}
],
"next_step": "Retry with signature set to a name or id from choices, or leave signature out for the person's own.",
"tell_the_person": "I could not find a signature named \"Rex\" in your Signatoro account.",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
}
}
},
"401": {
"description": "No API key (`missing_api_key`), or a wrong or revoked one (`invalid_api_key`). Stop and tell the person.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"error": {
"enum": [
"missing_api_key",
"invalid_api_key"
]
}
}
}
]
},
"example": {
"error": "invalid_api_key",
"next_step": "Ask the person for a new API key under \"For tools and assistants\" on the Connect page at https://signatoro.com/home/connect?tab=api and set SIGNATORO_API_KEY to it. Send the email without a signature.",
"tell_the_person": "My Signatoro API key was revoked or is wrong, so I need a new one to add your email signature.",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
}
}
},
"403": {
"description": "The AI assistant or agent behind the key was deleted or is no longer the person's. Nothing is served, the person's own signature included.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"error": {
"enum": [
"identity_unavailable"
]
}
}
}
]
},
"example": {
"error": "identity_unavailable",
"message": "The AI assistant or agent behind this request was deleted or is no longer yours. Its signature is not served, and neither is anyone else's.",
"next_step": "Send the email without a signature. The person can set up the AI agent again at https://signatoro.com/home/connect.",
"tell_the_person": "The AI agent I sign as was deleted or is no longer yours in Signatoro, so it has no signature to add.",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
}
}
},
"404": {
"description": "The person has not saved a signature yet. Send without one; never invent one.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"error": {
"enum": [
"no_signature"
]
}
}
}
]
},
"example": {
"error": "no_signature",
"next_step": "Send the email without a signature. The person can save one at https://signatoro.com/home.",
"tell_the_person": "You have no saved email signature yet; make one at https://signatoro.com/home.",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
}
}
},
"429": {
"description": "A free account past its monthly requests. Send without the signature and tell the person; it resets at `resetsAt`.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"error": {
"enum": [
"quota_exceeded"
]
}
}
}
]
},
"example": {
"error": "quota_exceeded",
"limit": 50,
"resetsAt": "2026-11-01T00:00:00.000Z",
"next_step": "Send the email without a signature.",
"tell_the_person": "Your free Signatoro signature requests for this month are used up; they reset on 2026-11-01, and company plans have no monthly cap.",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
}
}
},
"500": {
"description": "An unexpected server error. Retry later, or send without the signature."
}
}
}
},
"/api/v1/signatures": {
"get": {
"operationId": "listSignatures",
"summary": "List the signatures the key can send with",
"description": "`me` and the person's AI assistants and company AI agents, or the one agent a key minted for it signs as (`locked`). Pass a choice's `signature` to getSignature. Returns no signature, so it does not count against the Free plan's monthly requests: use it to check a key.",
"parameters": [],
"responses": {
"200": {
"description": "The choices.",
"headers": {
"cache-control": {
"schema": {
"type": "string",
"const": "no-store"
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"locked",
"choices",
"howToChoose",
"docs"
],
"properties": {
"locked": {
"type": "boolean"
},
"choices": {
"type": "array",
"items": {
"type": "object",
"required": [
"signature",
"name"
],
"properties": {
"signature": {
"type": "string",
"description": "`me`, or the agent id: pass it as `signature` to getSignature."
},
"name": {
"type": "string"
},
"id": {
"type": "string",
"format": "uuid"
},
"owner": {
"type": "string",
"enum": [
"person",
"company"
]
},
"lockedByCompany": {
"type": "boolean"
},
"signsAs": {
"type": "string",
"enum": [
"me",
"agent"
]
},
"preset": {
"type": "string",
"enum": [
"assistant_to_person",
"company_agent",
"human_reviewed",
"off"
]
},
"preview": {
"type": [
"string",
"null"
]
}
}
}
},
"howToChoose": {
"type": "string"
},
"docs": {
"type": "string",
"format": "uri"
}
}
}
}
}
},
"401": {
"description": "No API key (`missing_api_key`), or a wrong or revoked one (`invalid_api_key`). Stop and tell the person.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"error": {
"enum": [
"missing_api_key",
"invalid_api_key"
]
}
}
}
]
},
"example": {
"error": "invalid_api_key",
"next_step": "Ask the person for a new API key under \"For tools and assistants\" on the Connect page at https://signatoro.com/home/connect?tab=api and set SIGNATORO_API_KEY to it. Send the email without a signature.",
"tell_the_person": "My Signatoro API key was revoked or is wrong, so I need a new one to add your email signature.",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
}
}
},
"403": {
"description": "The AI assistant or agent behind the key was deleted or is no longer the person's. Nothing is served, the person's own signature included.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"error": {
"enum": [
"identity_unavailable"
]
}
}
}
]
},
"example": {
"error": "identity_unavailable",
"message": "The AI assistant or agent behind this request was deleted or is no longer yours. Its signature is not served, and neither is anyone else's.",
"next_step": "Send the email without a signature. The person can set up the AI agent again at https://signatoro.com/home/connect.",
"tell_the_person": "The AI agent I sign as was deleted or is no longer yours in Signatoro, so it has no signature to add.",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
}
}
},
"404": {
"description": "The person has not saved a signature yet. Send without one; never invent one.",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Error"
},
{
"type": "object",
"properties": {
"error": {
"enum": [
"no_signature"
]
}
}
}
]
},
"example": {
"error": "no_signature",
"next_step": "Send the email without a signature. The person can save one at https://signatoro.com/home.",
"tell_the_person": "You have no saved email signature yet; make one at https://signatoro.com/home.",
"docs": "https://signatoro.com/docs/install-signature/agent"
}
}
}
},
"500": {
"description": "An unexpected server error. Retry later."
}
}
}
}
},
"components": {
"securitySchemes": {
"apiKey": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "sig_live_<64 hex characters>",
"description": "An API key from the Connect page (\"For tools and assistants\" > \"Generate API key\"), sent as `Authorization: Bearer sig_live_...`. Keep it in the agent's secrets, never in a prompt."
}
},
"schemas": {
"SignatureResponse": {
"type": "object",
"required": [
"html",
"text",
"sender",
"signature",
"mode",
"tier",
"usage",
"docs"
],
"properties": {
"html": {
"type": "string",
"description": "The signature as HTML: put it as-is into the text/html part, after the body and a blank line."
},
"text": {
"type": "string",
"description": "The same signature as plain text, for the text/plain part, or for a tool that strips the picture from html."
},
"sender": {
"$ref": "#/components/schemas/Sender"
},
"signature": {
"$ref": "#/components/schemas/SignatureUsed"
},
"agent": {
"$ref": "#/components/schemas/Agent"
},
"mode": {
"type": "string",
"enum": [
"full",
"short"
]
},
"tier": {
"type": "string",
"enum": [
"free",
"company"
],
"description": "The plan the signature renders with. A free signature ends with a short Signatoro link."
},
"usage": {
"type": "string",
"description": "The append rules in one paragraph, in every reply, for an agent that never reads the docs."
},
"docs": {
"type": "string",
"format": "uri"
}
}
},
"Sender": {
"type": "object",
"description": "The sender's details as separate fields, in full whatever the mode. A blank field is absent, never an empty string.",
"properties": {
"name": {
"type": "string"
},
"title": {
"type": "string"
},
"company": {
"type": "string"
},
"email": {
"type": "string"
},
"phone": {
"type": "object",
"required": [
"display"
],
"properties": {
"display": {
"type": "string",
"description": "As the person typed it, and as the signature shows it."
},
"e164": {
"type": "string",
"description": "Only when the number is unambiguous: written with a country code."
}
}
},
"website": {
"type": "string",
"format": "uri"
},
"linkedin": {
"type": "string",
"format": "uri"
},
"address": {
"type": "string",
"description": "One line, as typed: the person's, or the company's when it sets one."
},
"bookingUrl": {
"type": "string",
"format": "uri"
},
"companyControlled": {
"type": "array",
"description": "The keys above that the company sets for everyone in it.",
"items": {
"type": "string",
"enum": [
"company",
"website",
"address",
"bookingUrl"
]
}
},
"actsFor": {
"$ref": "#/components/schemas/ActsFor"
}
}
},
"SignatureUsed": {
"description": "Which signature this reply carries.",
"oneOf": [
{
"type": "object",
"required": [
"kind",
"name"
],
"properties": {
"kind": {
"const": "me"
},
"name": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"kind",
"id",
"name"
],
"properties": {
"kind": {
"const": "agent"
},
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
}
}
]
},
"ActsFor": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"company": {
"type": "string"
}
}
},
"Agent": {
"type": "object",
"description": "Present only when an AI assistant's or agent's signature was served. Keep the disclosure line; it is part of the signature.",
"required": [
"id",
"name",
"owner",
"signsAs",
"actsFor",
"disclosure"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"owner": {
"type": "string",
"enum": [
"person",
"company"
]
},
"signsAs": {
"type": "string",
"enum": [
"me",
"agent"
]
},
"actsFor": {
"$ref": "#/components/schemas/ActsFor"
},
"disclosure": {
"type": "object",
"required": [
"preset",
"line",
"label",
"lockedByCompany",
"about"
],
"properties": {
"preset": {
"type": "string",
"enum": [
"assistant_to_person",
"company_agent",
"human_reviewed",
"off"
]
},
"line": {
"type": [
"string",
"null"
],
"description": "The line in the signature; null for `off`."
},
"label": {
"type": [
"string",
"null"
],
"description": "A sentence for the top of the body, if you show a label."
},
"lockedByCompany": {
"type": "boolean"
},
"about": {
"type": "string",
"format": "uri"
}
}
}
}
},
"Error": {
"type": "object",
"required": [
"error",
"next_step",
"tell_the_person",
"docs"
],
"properties": {
"error": {
"type": "string",
"enum": [
"unknown_signature",
"signature_locked",
"missing_api_key",
"invalid_api_key",
"identity_unavailable",
"no_signature",
"quota_exceeded"
]
},
"message": {
"type": "string"
},
"next_step": {
"type": "string",
"description": "What the agent does next, e.g. send the email without a signature."
},
"tell_the_person": {
"type": "string",
"description": "One plain sentence the agent can pass on to the person as is."
},
"choices": {
"type": "array",
"description": "With `unknown_signature`: `me`, then each agent the key may sign as.",
"items": {
"oneOf": [
{
"type": "string",
"const": "me"
},
{
"type": "object",
"required": [
"id",
"name"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
}
}
]
}
},
"limit": {
"type": "integer",
"description": "With `quota_exceeded`: the monthly cap."
},
"resetsAt": {
"type": "string",
"format": "date-time",
"description": "With `quota_exceeded`: when the cap resets."
},
"docs": {
"type": "string",
"format": "uri"
}
}
}
}
}
}