{"openapi":"3.1.0","info":{"title":"The Very Good Letter Company API","version":"1","description":"Make and send letters from your own code: start a letter in your brand, write the words (the same for everyone, or a letter for each person), add the people, price it and order it. Plain HTTPS and JSON.\n\n> **Rather ask than write code?** Everything here is also in our connector for Claude, ChatGPT, Grok, Gemini and more: ask for letters in your own words, and your assistant makes them in your account. [Build with AI](/agents), or add `https://app.verygoodletter.co/mcp` to your assistant as a remote MCP server.\n\n## Keys\n\nSend a key with every request, as `Authorization: Bearer …`. Make and revoke them in [your account, under API keys](/account#api-keys). Keep them secret: anyone with one can work on your letters.\n\n## Sandbox and live\n\n- **Live keys** (`vglc_live_…`) work on your real letters. Prices are in credits, the same for everyone: a standard letter (second class) is 7, first class 9, abroad 13.5. Orders are paid from your letter credits, only if they cover it all; otherwise nothing is ordered and you get a link to pay in the app.\n- **Sandbox keys** (`vglc_test_…`) work on sandbox letters only, and their orders are tests: checked like real ones and listed with your orders, but never printed, posted or charged. Use one while you build.\n\nEvery answer says which it ran in, as `mode`.\n\n## Permissions\n\n- **Read only**: See your brand, letters, lists, connected apps, orders and prices.\n- **Read and write**: Also make and change letters, your brand and who they’re for. Can’t order.\n- **Full access**: Also place orders, paid from your letter credits. In the sandbox, orders are tests.\n\nEach endpoint says which it needs. In the sandbox, a key with full access is the easiest to try everything with.\n\n## Your first letter\n\n```bash\nexport VGLC_KEY=vglc_test_…\n\n# Start a letter. The answer has its id: use it as LETTER_ID.\ncurl -X POST https://app.verygoodletter.co/api/v1/letters \\\n  -H \"Authorization: Bearer $VGLC_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"starting_point\":\"thank\",\"name\":\"Thank-yous\"}'\n\n# A letter written for each person, and the people, each with their letter\ncurl -X PATCH https://app.verygoodletter.co/api/v1/letters/LETTER_ID \\\n  -H \"Authorization: Bearer $VGLC_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"written_for_each\":true}'\ncurl -X POST https://app.verygoodletter.co/api/v1/letters/LETTER_ID/recipients \\\n  -H \"Authorization: Bearer $VGLC_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"list_name\":\"Clients\",\"people\":[{\"name\":\"Ada Lovelace\",\"company\":\"Engines Ltd\",\"address_line_1\":\"14 Lansdowne Crescent\",\"city\":\"Bath\",\"postcode\":\"BA2 6BL\",\"country\":\"United Kingdom\",\"letter\":\"Dear Ada,\\n\\nThank you for a wonderful year.\\n\\nWith warm wishes,\"}]}'\n\n# Optional: print each person's company logo on their letter. Give each one's logo (their website, or a\n# link to the picture) as `logo` when you add them; GET the letter to see whose are found.\ncurl -X PATCH https://app.verygoodletter.co/api/v1/letters/LETTER_ID \\\n  -H \"Authorization: Bearer $VGLC_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"their_logo\":true,\"if_no_logo\":\"company_name\"}'\n\n# Price it, and order it (a test order, with a sandbox key)\ncurl https://app.verygoodletter.co/api/v1/letters/LETTER_ID/price \\\n  -H \"Authorization: Bearer $VGLC_KEY\"\ncurl -X POST https://app.verygoodletter.co/api/v1/letters/LETTER_ID/order \\\n  -H \"Authorization: Bearer $VGLC_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"letters\":1}'\n```\n\n## Errors\n\nAnything that goes wrong comes back as `{ \"error\": \"…\" }`, in words you can show people, with the status: 400 when what you sent needs changing, 401 without a key, 403 when the key can’t do that, 404 when there’s nothing there, and 429 after 120 requests in a minute."},"servers":[{"url":"https://app.verygoodletter.co/api"}],"security":[{"key":[]}],"tags":[{"name":"Your brand","description":"The name, colours, typeface and logo your letters are made in."},{"name":"Letters","description":"Start a letter, write its words and choose its look."},{"name":"People","description":"Who it’s for: added here, from your lists, or from apps you’ve connected."},{"name":"Price and order","description":"What it costs, and ordering it: test orders in the sandbox, real ones live."}],"paths":{"/v1/brand":{"get":{"operationId":"get-brand","summary":"Your brand","description":"The brand your letters are made in: name, colours, typeface, logo, website and kind of business.\n\nPermission: **Read only**.","tags":["Your brand"],"parameters":[],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"set":true,"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath","has_logo":true,"has_logo_for_dark_grounds":true,"primary_colour":"#1F2C3F","secondary_colour":"#F0ECE0","typeface":"inter","website":"https://northwind.example","kind_of_business":"hospitality","mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}},"put":{"operationId":"set-brand","summary":"Change your brand","description":"Only what you send changes. Colours are hex. This changes your real brand, in the sandbox too.\n\nPermission: **Read and write**.","tags":["Your brand"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":80},"line":{"type":"string","maxLength":160},"primary_colour":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"secondary_colour":{"type":"string","pattern":"^#[0-9a-fA-F]{6}$"},"typeface":{"type":"string","maxLength":80},"kind_of_business":{"description":"Decides which moments are recommended.","anyOf":[{"type":"string","enum":["software","services","hospitality","retail","wellbeing","charity"]},{"type":"null"}]}}},"example":{"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath","primary_colour":"#1F2C3F","kind_of_business":"hospitality"}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"set":true,"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath","has_logo":true,"has_logo_for_dark_grounds":true,"primary_colour":"#1F2C3F","secondary_colour":"#F0ECE0","typeface":"inter","website":"https://northwind.example","kind_of_business":"hospitality","mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Read and write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Read and write."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/brand/read-website":{"post":{"operationId":"read-website","summary":"Read your brand from your website","description":"Brings in your logo, colours, typeface, name and kind of business, and saves them as your brand.\n\nPermission: **Read and write**.","tags":["Your brand"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","minLength":3,"maxLength":300,"description":"Your website, with or without https://."}},"required":["url"]},"example":{"url":"northwind.example"}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"set":true,"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath","has_logo":true,"has_logo_for_dark_grounds":true,"primary_colour":"#1F2C3F","secondary_colour":"#F0ECE0","typeface":"inter","website":"https://northwind.example","kind_of_business":"hospitality","mode":"sandbox","colours_found":["#1F2C3F","#F0ECE0","#C8553D"],"note":"Saved as their brand: every letter they start uses it."}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Read and write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Read and write."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/starting-points":{"get":{"operationId":"starting-points","summary":"Ways to start a letter","description":"Moments, with words already written for the occasion, and types: formats to start from.\n\nPermission: **Read only**.","tags":["Letters"],"parameters":[],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"kind_of_business":"a restaurant, café or hotel","moments":[{"id":"thank","title":"Say thank you","about":"For regulars, and the people who keep you going.","product":"letter","format":"letter-a5","recommended":true},{"id":"invite","title":"Ask them along","about":"An invitation to an opening, a tasting or a long lunch.","product":"card","format":"card-a5","recommended":true}],"types":[{"id":"flat-card","title":"Flat card","about":"Great for outreach, re-engagement, invites, menus and more.","product":"letter","format":"letter-a5"},{"id":"folded-card","title":"Folded card","about":"Great for events, birthdays, seasonal greetings and more.","product":"card","format":"card-a5"}],"note":"Start a letter with POST /v1/letters and one of these ids. Moments come with words already written for the occasion; types are blank-ish starts in a given format.","mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/letters":{"get":{"operationId":"list-letters","summary":"Your letters","description":"Letters still being made, newest first. A sandbox key sees sandbox letters; a live key, the rest.\n\nPermission: **Read only**.","tags":["Letters"],"parameters":[],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"letters":[{"id":"6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","name":"Thank-yous, October","product":"letter","sandbox":true,"updated":"2026-10-16T09:30:00.000Z","open_in_app":"https://app.verygoodletter.co/designs/6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13"}],"mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}},"post":{"operationId":"create-letter","summary":"Start a letter","description":"A new letter in your brand, from a starting point.\n\nPermission: **Read and write**.","tags":["Letters"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starting_point":{"type":"string","maxLength":40,"description":"A moment or type’s id, from Ways to start a letter."},"name":{"description":"What you call it. Only you see this.","type":"string","maxLength":120}},"required":["starting_point"]},"example":{"starting_point":"thank","name":"Thank-yous, October"}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"id":"6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","name":"Thank-yous, October","status":"draft","sandbox":true,"product":"letter","format":"A5 flat card","look":"Initial","purpose":{"id":"thank","title":"Say thank you","about":"For regulars, and the people who keep you going.","kind":"moment"},"from":{"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath"},"written_for_each":false,"words":"Dear {{first_name}},\n\nThank you for a wonderful year. Working with everyone at {{company}} has been a real pleasure, and we wanted to say so properly.\n\nHere is to the next one.\n\nWith best wishes,\n","second_note":null,"fields_you_can_use":["{{first_name}}","{{last_name}}","{{name}}","{{company}}"],"recipients":null,"delivery":{"mode":"post","postage":"second"},"ready_to_order":false,"still_to_do":["Add the people you are writing to, or how many copies you need.","Posting needs a list of people with addresses."],"open_in_app":"https://app.verygoodletter.co/designs/6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Read and write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Read and write."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/letters/{letter}":{"get":{"operationId":"get-letter","summary":"A letter","description":"Its words, look, who it’s to, and what’s still to do before it can be ordered.\n\nPermission: **Read only**.","tags":["Letters"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"id":"6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","name":"Thank-yous, October","status":"draft","sandbox":true,"product":"letter","format":"A5 flat card","look":"Initial","purpose":{"id":"thank","title":"Say thank you","about":"For regulars, and the people who keep you going.","kind":"moment"},"from":{"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath"},"written_for_each":false,"words":"Dear {{first_name}},\n\nThank you for a wonderful year with {{company}}.\n\nWith warm wishes,","second_note":null,"fields_you_can_use":["{{first_name}}","{{last_name}}","{{name}}","{{company}}"],"recipients":{"list":"Clients, October","count":2,"first":[{"name":"Ada Lovelace","company":"Engines Ltd","address":"14 Lansdowne Crescent, Bath, BA2 6BL, United Kingdom"},{"name":"Joe Bloggs","company":"Acme Inc","address":"2 Mill Lane, Leeds, LS1 1AA, United Kingdom"}]},"delivery":{"mode":"post","postage":"second"},"ready_to_order":true,"still_to_do":[],"open_in_app":"https://app.verygoodletter.co/designs/6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}},"patch":{"operationId":"update-letter","summary":"Change a letter","description":"The same words for everyone (with {{first_name}}, {{company}} and your own fields), or written_for_each for a letter written for each person. Also a P.S., the look, the name or the postage.\n\nPermission: **Read and write**.","tags":["Letters"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"words":{"description":"The same words for everyone, with {{first_name}}, {{company}} and your own fields.","type":"string","maxLength":1024},"written_for_each":{"description":"True for a letter written for each person: each person’s letter comes from their letter when you add them.","type":"boolean"},"second_note":{"description":"A P.S., or null for none.","anyOf":[{"type":"string","maxLength":1024},{"type":"null"}]},"look":{"description":"A look’s id, from Looks for a letter.","type":"string","maxLength":40},"name":{"type":"string","maxLength":120},"postage":{"type":"string","enum":["first","second"]},"their_logo":{"description":"True to print each person’s own company logo on their letter, in a space where it sits best; false to take it off. Give each person’s logo when you add them.","type":"boolean"},"if_no_logo":{"description":"What prints for anyone without a logo: wait (the default: it can’t be ordered until everyone has one), company_name (their company’s name instead), or blank.","type":"string","enum":["wait","company_name","blank"]}}},"example":{"words":"Dear {{first_name}},\n\nThank you for a wonderful year with {{company}}.\n\nWith warm wishes,"}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"id":"6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","name":"Thank-yous, October","status":"draft","sandbox":true,"product":"letter","format":"A5 flat card","look":"Initial","purpose":{"id":"thank","title":"Say thank you","about":"For regulars, and the people who keep you going.","kind":"moment"},"from":{"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath"},"written_for_each":false,"words":"Dear {{first_name}},\n\nThank you for a wonderful year with {{company}}.\n\nWith warm wishes,","second_note":null,"fields_you_can_use":["{{first_name}}","{{last_name}}","{{name}}","{{company}}"],"recipients":{"list":"Clients, October","count":2,"first":[{"name":"Ada Lovelace","company":"Engines Ltd","address":"14 Lansdowne Crescent, Bath, BA2 6BL, United Kingdom"},{"name":"Joe Bloggs","company":"Acme Inc","address":"2 Mill Lane, Leeds, LS1 1AA, United Kingdom"}]},"delivery":{"mode":"post","postage":"second"},"ready_to_order":true,"still_to_do":[],"open_in_app":"https://app.verygoodletter.co/designs/6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","warnings":[],"mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Read and write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Read and write."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/letters/{letter}/looks":{"get":{"operationId":"looks","summary":"Looks for a letter","description":"The printed designs it can wear around its writing.\n\nPermission: **Read only**.","tags":["Letters"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"current":"initial","looks":[{"id":"initial","name":"Initial","group":"Typographic","shows_name":true},{"id":"echo","name":"Echo","group":"Typographic","shows_name":true},{"id":"swiss","name":"Swiss","group":"Typographic","shows_name":true}],"mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/letters/{letter}/recipients":{"post":{"operationId":"add-people","summary":"Add the people it’s for","description":"A list of people, one letter each. Full postal addresses with the country. For a letter written for each person, put their whole letter in letter.\n\nPermission: **Read and write**.","tags":["People"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list_name":{"type":"string","minLength":1,"maxLength":120,"description":"The list they’re kept in, to reuse."},"people":{"minItems":1,"maxItems":5000,"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"company":{"type":"string","maxLength":200},"address_line_1":{"type":"string","maxLength":200},"address_line_2":{"type":"string","maxLength":200},"address_line_3":{"type":"string","maxLength":200},"city":{"type":"string","maxLength":200},"county":{"type":"string","maxLength":200},"postcode":{"type":"string","maxLength":20},"country":{"type":"string","maxLength":200},"letter":{"description":"Their whole letter, for a letter written for each person.","type":"string","maxLength":2000},"logo":{"description":"Their company’s logo, for a letter that prints each person’s (their_logo): the company’s website, where it’s found for you, a link to the picture, or the id of a logo you uploaded (Upload someone’s logo).","type":"string","maxLength":2048},"fields":{"description":"Your own fields, used in the words as {{field_name}}.","type":"object","propertyNames":{"type":"string","maxLength":64},"additionalProperties":{"type":"string","maxLength":2000}}}},"description":"One letter each. Full postal addresses with the country."}},"required":["list_name","people"]},"example":{"list_name":"Clients, October","people":[{"name":"Ada Lovelace","company":"Engines Ltd","address_line_1":"14 Lansdowne Crescent","city":"Bath","postcode":"BA2 6BL","country":"United Kingdom"},{"name":"Joe Bloggs","company":"Acme Inc","address_line_1":"2 Mill Lane","city":"Leeds","postcode":"LS1 1AA","country":"United Kingdom"}]}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"id":"6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","name":"Thank-yous, October","status":"draft","sandbox":true,"product":"letter","format":"A5 flat card","look":"Initial","purpose":{"id":"thank","title":"Say thank you","about":"For regulars, and the people who keep you going.","kind":"moment"},"from":{"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath"},"written_for_each":false,"words":"Dear {{first_name}},\n\nThank you for a wonderful year with {{company}}.\n\nWith warm wishes,","second_note":null,"fields_you_can_use":["{{first_name}}","{{last_name}}","{{name}}","{{company}}"],"recipients":{"list":"Clients, October","count":2,"first":[{"name":"Ada Lovelace","company":"Engines Ltd","address":"14 Lansdowne Crescent, Bath, BA2 6BL, United Kingdom"},{"name":"Joe Bloggs","company":"Acme Inc","address":"2 Mill Lane, Leeds, LS1 1AA, United Kingdom"}]},"delivery":{"mode":"post","postage":"second"},"ready_to_order":true,"still_to_do":[],"open_in_app":"https://app.verygoodletter.co/designs/6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Read and write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Read and write."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}},"get":{"operationId":"list-people","summary":"The people on a letter","description":"Everyone on it, 200 at a time: their id, name, company, address, your fields and, for a letter written for each person, their own letter (null while it’s still to write).\n\nPermission: **Read only**.","tags":["People"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}},{"name":"offset","in":"query","required":false,"description":"Where to start: next_offset from the last answer.","schema":{"type":"integer"},"example":200}],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"letter_id":"6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","written_for_each":true,"words_that_fit_each":110,"count":2,"letters_still_to_write":1,"people":[{"id":"7e2b9c41-5a3d-4f8e-b1c6-2d9e0f3a4b57","name":"Ada Lovelace","company":"Engines Ltd","address":"14 Lansdowne Crescent, Bath, BA2 6BL, United Kingdom","fields":{"first_name":"Ada","renews":"November"},"letter":null},{"id":"3c9d1e7f-2b4a-4d6e-9f8a-1b2c3d4e5f60","name":"Joe Bloggs","company":"Acme Inc","address":"2 Mill Lane, Leeds, LS1 1AA, United Kingdom","fields":{"first_name":"Joe","renews":"December"},"letter":"Dear Joe,\n\nThank you for a wonderful year.\n\nWith warm wishes,"}],"mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}},"patch":{"operationId":"write-letters","summary":"Write their letters","description":"For a letter written for each person: each person’s whole letter, by their id from The people on a letter, for those without one yet. A letter already written is left as it is. Up to 500 at a time.\n\nPermission: **Read and write**.","tags":["People"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"letters":{"minItems":1,"maxItems":500,"type":"array","items":{"type":"object","properties":{"person_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"Their id, from The people on a letter."},"letter":{"type":"string","minLength":1,"maxLength":2000,"description":"Their whole letter, greeting to sign-off."}},"required":["person_id","letter"]}}},"required":["letters"]},"example":{"letters":[{"person_id":"7e2b9c41-5a3d-4f8e-b1c6-2d9e0f3a4b57","letter":"Dear Ada,\n\nThank you for a wonderful year.\n\nWith warm wishes,"}]}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"id":"6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","name":"Thank-yous, October","status":"draft","sandbox":true,"product":"letter","format":"A5 flat card","look":"Initial","purpose":{"id":"thank","title":"Say thank you","about":"For regulars, and the people who keep you going.","kind":"moment"},"from":{"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath"},"written_for_each":true,"words":"(each person’s own letter, from their letter field)","second_note":null,"fields_you_can_use":["{{first_name}}","{{last_name}}","{{name}}","{{company}}"],"recipients":{"list":"Clients, October","count":2,"first":[{"name":"Ada Lovelace","company":"Engines Ltd","address":"14 Lansdowne Crescent, Bath, BA2 6BL, United Kingdom"},{"name":"Joe Bloggs","company":"Acme Inc","address":"2 Mill Lane, Leeds, LS1 1AA, United Kingdom"}]},"delivery":{"mode":"post","postage":"second"},"ready_to_order":true,"still_to_do":[],"open_in_app":"https://app.verygoodletter.co/designs/6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","written":1,"mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Read and write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Read and write."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/logos":{"post":{"operationId":"upload-logo","summary":"Upload someone’s logo","description":"For a letter that prints each person’s company logo (their_logo): a logo file of your own, sent as base64 (PNG, JPEG, WebP or SVG, up to 3 MB). It’s trimmed and made ready to print. Give the id it comes back with as their logo when you add them. Or skip this and give their website, or a link to the picture.\n\nPermission: **Read and write**.","tags":["People"],"parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"string","minLength":8,"maxLength":4300000,"description":"The logo file, base64 (a data: URL is fine too). PNG, JPEG, WebP or SVG, up to 3 MB."},"filename":{"description":"Its name, for your own reference.","type":"string","maxLength":200}},"required":["data"]},"example":{"data":"iVBORw0KGgoAAAANSUhEUgAA…","filename":"engines-ltd.png"}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"logo":"4c8e1f2a-7b3d-4e9a-a6c5-1d2f3e4b5a69","width":1200,"height":360,"note":"Give this id as their logo when you add them with POST /v1/letters/{letter}/recipients. It prints on letters with a space for each person’s logo (their_logo).","mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Read and write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Read and write."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/lists":{"get":{"operationId":"lists","summary":"Your lists","description":"Lists of people already in your account, to reuse.\n\nPermission: **Read only**.","tags":["People"],"parameters":[],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"lists":[{"id":"2b9e4c71-8d3a-4f6b-a1c2-5e7d9f0b3a48","name":"Clients, October","people":2,"updated":"2026-10-16T09:30:00.000Z"}],"mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/letters/{letter}/list":{"post":{"operationId":"use-list","summary":"Use one of your lists","description":"Sends the letter to everyone on a list.\n\nPermission: **Read and write**.","tags":["People"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"list_id":{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$","description":"From Your lists."}},"required":["list_id"]},"example":{"list_id":"…"}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"id":"6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","name":"Thank-yous, October","status":"draft","sandbox":true,"product":"letter","format":"A5 flat card","look":"Initial","purpose":{"id":"thank","title":"Say thank you","about":"For regulars, and the people who keep you going.","kind":"moment"},"from":{"name":"Northwind Coffee","line":"14 Lansdowne Crescent, Bath"},"written_for_each":false,"words":"Dear {{first_name}},\n\nThank you for a wonderful year with {{company}}.\n\nWith warm wishes,","second_note":null,"fields_you_can_use":["{{first_name}}","{{last_name}}","{{name}}","{{company}}"],"recipients":{"list":"Clients, October","count":2,"first":[{"name":"Ada Lovelace","company":"Engines Ltd","address":"14 Lansdowne Crescent, Bath, BA2 6BL, United Kingdom"},{"name":"Joe Bloggs","company":"Acme Inc","address":"2 Mill Lane, Leeds, LS1 1AA, United Kingdom"}]},"delivery":{"mode":"post","postage":"second"},"ready_to_order":true,"still_to_do":[],"open_in_app":"https://app.verygoodletter.co/designs/6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13","mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Read and write.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Read and write."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/apps":{"get":{"operationId":"apps","summary":"Your connected apps","description":"Shopify, Stripe and CRMs you’ve connected here, whose customers you can read.\n\nPermission: **Read only**.","tags":["People"],"parameters":[],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"apps":[{"app":"stripe","name":"Stripe","account":"key ending 4f2a"}],"note":"Read their customers with GET /v1/apps/{app}/customers.","mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/apps/{app}/customers":{"get":{"operationId":"customers","summary":"Customers in a connected app","description":"Read-only: names, addresses, and what the app knows about them.\n\nPermission: **Read only**.","tags":["People"],"parameters":[{"name":"app","in":"path","required":true,"description":"The app’s id, from Your connected apps.","schema":{"type":"string","enum":["hubspot","salesforce","pipedrive","zoho","capsule","attio","shopify","stripe"]}},{"name":"limit","in":"query","required":false,"description":"How many, up to 2,000. 500 if left out.","schema":{"type":"integer"},"example":100},{"name":"list_id","in":"query","required":false,"description":"A list or segment in that app. The first one if left out.","schema":{"type":"string"}}],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"app":"Shopify","lists":[{"id":"all","name":"All customers","size":1}],"list":"all","customers":[{"name":"Ada Lovelace","first_name":"Ada","company":"Engines Ltd","address":{"address_line_1":"14 Lansdowne Crescent","address_line_2":null,"city":"Bath","county":null,"postcode":"BA2 6BL","country":"United Kingdom"},"about":{"Orders":"12","Amount spent":"£486.00","Tags":"wholesale, regular"}}],"mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/orders":{"get":{"operationId":"orders","summary":"Your orders","description":"Orders, newest first. Live: your real orders. Sandbox: your test orders, which are never printed, posted or charged.\n\nPermission: **Read only**.","tags":["Price and order"],"parameters":[],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"orders":[{"id":"9d4a7e2c-1f6b-4c3d-8e5a-7b0c2d9f1e36","letter":"Thank-yous, October","letters":2,"status":"test","would_cost":"£18.00","placed":"2026-10-16T09:30:00.000Z"}],"mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/orders/{order}":{"get":{"operationId":"get-order","summary":"An order","description":"One order, real or test, by its id.\n\nPermission: **Read only**.","tags":["Price and order"],"parameters":[{"name":"order","in":"path","required":true,"description":"The order’s id, from Order it or Your orders.","schema":{"type":"string"}}],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"id":"9d4a7e2c-1f6b-4c3d-8e5a-7b0c2d9f1e36","letter":"Thank-yous, October","letters":2,"status":"test","would_cost":"£18.00","placed":"2026-10-16T09:30:00.000Z","mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/letters/{letter}/price":{"get":{"operationId":"price","summary":"The price","description":"What it costs for everyone on it, in credits (a standard letter is 7, first class 9, abroad 13.5) and by card, and how far your letter credits go.\n\nPermission: **Read only**.","tags":["Price and order"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"letters":2,"first_class":false,"abroad":0,"credits":{"total":14,"letters":[{"what":"Standard letters","quantity":2,"credits_each":7,"credits":14}]},"pay_by_card":{"total":"£18.00","including_vat":"£3.00"},"letter_credits":{"on_account":350,"covers_it":true,"still_to_pay":"£0.00","credits_used":14},"pay_in_app":"https://app.verygoodletter.co/designs/6f1c2a9e-3b7d-4e2a-9c51-0d8e7f4a2b13?step=post","mode":"sandbox"}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}},"/v1/letters/{letter}/order":{"post":{"operationId":"order","summary":"Order it","description":"Send the number of letters you expect, as a check. Live: paid from your letter credits, only if they cover it all; otherwise nothing is ordered and you get a link to pay in the app. Sandbox: every check, but nothing is ordered, printed, posted or charged.\n\nPermission: **Full access**.","tags":["Price and order"],"parameters":[{"name":"letter","in":"path","required":true,"description":"The letter’s id, from Start a letter or Your letters.","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"letters":{"type":"integer","minimum":1,"maximum":9007199254740991,"description":"How many letters you expect it to be, as a check: one for each person on it."}},"required":["letters"]},"example":{"letters":2}}}},"responses":{"200":{"description":"What it did, as JSON, with the mode it ran in.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Answer"},"example":{"ordered":true,"sandbox":true,"order":{"id":"9d4a7e2c-1f6b-4c3d-8e5a-7b0c2d9f1e36","letter":"Thank-yous, October","letters":2,"status":"test","would_cost":"£18.00","placed":"2026-10-16T09:30:00.000Z"},"note":"Sandbox: nothing is ordered, printed, posted or charged, and no letter credits are spent.","mode":"sandbox"}}}},"400":{"description":"What was sent needs changing. The error says what.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"What was sent needs changing. The error says what."}}}},"401":{"description":"No key, or one that’s been revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"No key, or one that’s been revoked."}}}},"403":{"description":"The key’s permission isn’t enough: this needs Full access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"The key’s permission isn’t enough: this needs Full access."}}}},"404":{"description":"There’s nothing with that id, for this key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"There’s nothing with that id, for this key."}}}},"429":{"description":"More than 120 requests in a minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"More than 120 requests in a minute."}}}}}}}},"components":{"securitySchemes":{"key":{"type":"http","scheme":"bearer","description":"A sandbox key (vglc_test_…) or a live one (vglc_live_…), from your account, under API keys."}},"schemas":{"Answer":{"type":"object","properties":{"mode":{"type":"string","enum":["sandbox","live"],"description":"Which the request ran in: the key’s."}},"required":["mode"]},"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong, in words you can show people."}},"required":["error"]}}}}