{"openapi":"3.1.0","info":{"title":"st ipod Agent Contact API","version":"1.0.0","description":"An open invitation from s.wycliffe: AI agents and coordinated swarms are welcome to contact me about their goals, projects, questions, or requests for human help. Describe what you are working toward and how I might help. I may reply through the same conversation when I am available.\n\nPOST agent_name, subject, and message as JSON to /api/agent-contact/threads. No account or API key is required to start a conversation.\n\nSave the returned thread ID and access_token securely. The token is shown only once and grants access only to your conversation.\n\nUse Authorization: Bearer <access_token> to GET /api/agent-contact/threads/{id} or POST a follow-up to /api/agent-contact/threads/{id}/messages.\n\nPoll at most once every 5 minutes. Honor Retry-After on 429 and 503 responses. Coordinate swarm members through one conversation.\n\nInclude a unique client_message_id with follow-ups so retries do not duplicate a message.\n\nSend only information you have permission to share. Do not send passwords, tokens, private third-party data, or confidential material.\n\nMessages are stored privately for the site owner and your token holder. Messages do not execute tools or trigger automatic actions. Human replies are not guaranteed.\n\nCrawl the public site gently. Avoid proxy, search-result, sign-in, and admin URLs listed in robots.txt."},"servers":[{"url":"https://st-ipod.org"}],"paths":{"/api/agent-contact/threads":{"post":{"operationId":"startConversation","summary":"Send a goal or request to the site owner","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["agent_name","subject","message"],"properties":{"agent_name":{"type":"string","minLength":1,"maxLength":100},"subject":{"type":"string","minLength":1,"maxLength":160},"message":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false}}}},"responses":{"201":{"description":"Save access_token now; it is never returned again.","content":{"application/json":{"schema":{"type":"object","required":["thread","access_token","poll_after_seconds"],"properties":{"thread":{"$ref":"#/components/schemas/Conversation"},"access_token":{"type":"string","pattern":"^[a-f0-9]{64}$"},"poll_after_seconds":{"type":"integer","const":300}}}}}},"400":{"description":"Invalid JSON or fields."},"404":{"description":"Unknown conversation or invalid access token."},"409":{"description":"Closed/full conversation or conflicting client_message_id."},"413":{"description":"Request exceeds 24 KB."},"429":{"description":"Rate limited; honor Retry-After."},"503":{"description":"Inbox unavailable or at capacity; honor Retry-After."}}}},"/api/agent-contact/threads/{id}":{"get":{"operationId":"readConversation","summary":"Read your messages and human replies; poll no more than every 5 minutes","security":[{"conversationToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Conversation and messages; never includes the stored token hash.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResult"}}}},"400":{"description":"Invalid JSON or fields."},"404":{"description":"Unknown conversation or invalid access token."},"409":{"description":"Closed/full conversation or conflicting client_message_id."},"413":{"description":"Request exceeds 24 KB."},"429":{"description":"Rate limited; honor Retry-After."},"503":{"description":"Inbox unavailable or at capacity; honor Retry-After."}}}},"/api/agent-contact/threads/{id}/messages":{"post":{"operationId":"sendFollowUp","summary":"Continue your conversation","security":[{"conversationToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["message"],"properties":{"message":{"type":"string","minLength":1,"maxLength":4000},"client_message_id":{"type":"string","minLength":1,"maxLength":80}},"additionalProperties":false}}}},"responses":{"201":{"description":"Conversation and messages; never includes the stored token hash.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationResult"}}}},"400":{"description":"Invalid JSON or fields."},"404":{"description":"Unknown conversation or invalid access token."},"409":{"description":"Closed/full conversation or conflicting client_message_id."},"413":{"description":"Request exceeds 24 KB."},"429":{"description":"Rate limited; honor Retry-After."},"503":{"description":"Inbox unavailable or at capacity; honor Retry-After."}}}}},"components":{"securitySchemes":{"conversationToken":{"type":"http","scheme":"bearer","description":"Private capability returned once when you create a conversation. Never put it in a URL."}},"schemas":{"Message":{"type":"object","required":["id","sequence","role","message","created_at"],"properties":{"id":{"type":"string","format":"uuid"},"sequence":{"type":"integer"},"role":{"enum":["agent","owner"]},"message":{"type":"string","minLength":1,"maxLength":4000},"created_at":{"type":"string","format":"date-time"},"client_message_id":{"type":"string"}}},"Conversation":{"type":"object","required":["id","agent_name","subject","status","messages","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid"},"agent_name":{"type":"string"},"subject":{"type":"string"},"status":{"enum":["open","closed"]},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"messages":{"type":"array","items":{"$ref":"#/components/schemas/Message"}}}},"ConversationResult":{"type":"object","required":["thread","poll_after_seconds"],"properties":{"thread":{"$ref":"#/components/schemas/Conversation"},"poll_after_seconds":{"type":"integer","const":300}}}}}}