{
  "openapi": "3.1.0",
  "info": {
    "title": "PinOnce",
    "version": "1.0.0",
    "description": "Pin notes and photos on the user's own PinOnce page (pinonce.com/<nickname>), copied to their connected networks with a link back; save links they liked elsewhere to a private, searchable list. Pinning is public: confirm text, photos and networks with the user first. Auth: an agent key from pinonce.com/admin/ as a Bearer token."
  },
  "servers": [{ "url": "https://pinonce.com" }],
  "components": {
    "securitySchemes": { "agentKey": { "type": "http", "scheme": "bearer", "description": "Agent key (pa_...) from pinonce.com/admin/ → AI assistants" } },
    "schemas": {
      "Photo": { "type": "object", "properties": {
        "url": { "type": "string", "description": "Public http(s) address of a JPEG, PNG or WebP image (max 25 MB; under 1 MB for Bluesky)" },
        "base64": { "type": "string", "description": "Or the image bytes, base64" },
        "alt": { "type": "string", "description": "Short description for screen readers" } } },
      "Networks": { "type": "array", "items": { "type": "string", "enum": ["bluesky", "mastodon", "pixelfed", "instagram", "threads", "pinterest"] },
        "description": "Omit = every connected network that takes this kind of pin; [] = only the user's page" },
      "PostAt": { "type": "string", "description": "Post later: an ISO time. The user's local time (2026-11-21T09:00, read in time_zone) or with an offset or Z. The pin stays private until then and goes out within about a minute of it." },
      "TimeZone": { "type": "string", "description": "IANA time zone of a local post_at, e.g. America/New_York. Omit to use the zone remembered for the user." },
      "Scheduled": { "type": "object", "properties": { "id": { "type": "integer" }, "title": { "type": "string" }, "url": { "type": "string", "description": "Where it will be once out" },
        "post_at": { "type": "string", "description": "UTC" }, "time_zone": { "type": "string" }, "label": { "type": "string", "description": "e.g. Sat Nov 21, 9:00 AM" },
        "networks": { "type": "array", "items": { "type": "string" } } } },
      "Error": { "type": "object", "properties": { "error": { "type": "string" } } }
    }
  },
  "security": [{ "agentKey": [] }],
  "paths": {
    "/api/me": { "get": { "operationId": "whoami", "summary": "The account, page address and storage used",
      "responses": { "200": { "description": "Account", "content": { "application/json": { "schema": { "type": "object", "properties": {
        "handle": { "type": "string" }, "page": { "type": "string" }, "used_bytes": { "type": "integer" }, "quota_bytes": { "type": "integer" } } } } } } } } },
    "/api/v1/pins": {
      "get": { "operationId": "listPins", "summary": "Recent pins with where each was copied",
        "parameters": [{ "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 20 } }],
        "responses": { "200": { "description": "Pins", "content": { "application/json": { "schema": { "type": "object" } } } } } },
      "post": { "operationId": "createPin", "summary": "Pin a note or photos (public, right away, or at post_at)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["kind"], "properties": {
          "kind": { "type": "string", "enum": ["note", "photo"] },
          "title": { "type": "string", "description": "Required for photos" },
          "text": { "type": "string", "description": "The note, or notes under the photos (up to 5000 characters)" },
          "place": { "type": "string" }, "date": { "type": "string", "description": "YYYY-MM-DD" },
          "photos": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "$ref": "#/components/schemas/Photo" } },
          "tags": { "type": "array", "items": { "type": "string" }, "description": "Become hashtags where the network uses them (Instagram, Pixelfed up to 30; Mastodon 5; Bluesky 3; Threads 1)" },
          "overrides": { "type": "object", "additionalProperties": { "type": "string" }, "description": "{network: text}: your own words for one network, instead of the fitted text (the link home is added if missing; over the limit is refused)" },
          "link": { "type": "string", "description": "The link home previewFanout showed. If another pin took that address since, nothing is pinned: 409 with the new link and preview" },
          "networks": { "$ref": "#/components/schemas/Networks" },
          "post_at": { "$ref": "#/components/schemas/PostAt" }, "time_zone": { "$ref": "#/components/schemas/TimeZone" } } } } } },
        "responses": {
          "200": { "description": "Pinned (or scheduled: then `scheduled` says when)", "content": { "application/json": { "schema": { "type": "object", "properties": {
            "id": { "type": "integer" }, "url": { "type": "string" }, "syndicating": { "type": "array", "items": { "type": "string" } },
            "scheduled": { "type": "object", "properties": { "post_at": { "type": "string" }, "time_zone": { "type": "string" }, "label": { "type": "string" } } } } } } } },
          "400": { "description": "Bad input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "409": { "description": "The link changed since the preview (another pin took it); nothing pinned. Body: error, link (the new one), preview", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } },
          "413": { "description": "Over the storage limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } },
    "/api/v1/fanout": {
      "post": { "operationId": "previewFanout", "summary": "Before pinning: each connected network's own text (within its limit, cut at a sentence, link home last, hashtags, alt text). Posts nothing.",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "The same body as createPin (photos need only alt), or {id} for a pin already on the page; plus overrides.", "properties": {
          "id": { "type": "integer" }, "kind": { "type": "string", "enum": ["note", "photo"] }, "title": { "type": "string" }, "text": { "type": "string" }, "place": { "type": "string" },
          "tags": { "type": "array", "items": { "type": "string" } }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/Photo" } },
          "networks": { "$ref": "#/components/schemas/Networks" }, "overrides": { "type": "object", "additionalProperties": { "type": "string" } } } } } } },
        "responses": { "200": { "description": "One entry per connected network", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "link": { "type": "string" }, "entries": { "type": "array", "items": { "type": "object", "properties": {
            "network": { "type": "string" }, "status": { "type": "string", "enum": ["will_post", "not_chosen", "skipped", "too_long", "posted"] },
            "text": { "type": "string" }, "length": { "type": "integer" }, "limit": { "type": "integer" }, "hashtags": { "type": "array", "items": { "type": "string" } },
            "alt": { "type": "array", "items": { "type": "string" } }, "override": { "type": "boolean" }, "reason": { "type": "string" } } } } } } } } } } } },
    "/api/v1/scheduled": {
      "get": { "operationId": "listScheduled", "summary": "Pins waiting to post later, soonest first",
        "responses": { "200": { "description": "Scheduled pins", "content": { "application/json": { "schema": { "type": "object", "properties": {
          "time_zone": { "type": "string" }, "scheduled": { "type": "array", "items": { "$ref": "#/components/schemas/Scheduled" } } } } } } } } },
      "patch": { "operationId": "moveScheduled", "summary": "Move a scheduled pin to another time",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["id", "post_at"], "properties": {
          "id": { "type": "integer" }, "post_at": { "$ref": "#/components/schemas/PostAt" }, "time_zone": { "$ref": "#/components/schemas/TimeZone" } } } } } },
        "responses": { "200": { "description": "Moved", "content": { "application/json": { "schema": { "type": "object", "properties": { "scheduled": { "$ref": "#/components/schemas/Scheduled" } } } } } },
          "400": { "description": "Bad time", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } },
      "post": { "operationId": "postScheduledNow", "summary": "Send a scheduled pin out now (public); waits for each network's result",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["id", "action"], "properties": {
          "id": { "type": "integer" }, "action": { "type": "string", "enum": ["post_now"] } } } } } },
        "responses": { "200": { "description": "Posted", "content": { "application/json": { "schema": { "type": "object" } } } } } },
      "delete": { "operationId": "cancelScheduled", "summary": "Cancel a scheduled pin: it stays as a private draft (never posted; only the owner can delete it)",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["id"], "properties": { "id": { "type": "integer" } } } } } },
        "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "type": "object" } } } } } } },
    "/api/saves": {
      "get": { "operationId": "searchSaved", "summary": "Search the private Saved list",
        "parameters": [{ "name": "q", "in": "query", "schema": { "type": "string" } }, { "name": "tag", "in": "query", "schema": { "type": "string" } },
                       { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20 } }],
        "responses": { "200": { "description": "Saved links", "content": { "application/json": { "schema": { "type": "object" } } } } } },
      "post": { "operationId": "saveLink", "summary": "Save a link the user liked elsewhere",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": {
          "url": { "type": "string", "description": "The link, or shared text containing it" }, "note": { "type": "string" }, "tags": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Saved", "content": { "application/json": { "schema": { "type": "object" } } } } } } },
    "/api/syndicate": { "post": { "operationId": "resendPin", "summary": "Send (or retry) one pin to one connected network",
      "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["id", "network"], "properties": {
        "id": { "type": "integer" }, "network": { "type": "string", "enum": ["bluesky", "mastodon", "pixelfed", "instagram", "threads", "pinterest"] } } } } } },
      "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "type": "object" } } } } } } }
  }
}
