{"openapi":"3.1.0","info":{"title":"ppl agent API","version":"1.2.2","description":"REST API for ppl, the personal CRM for humans with AI agents. Most agents should use the hosted MCP server at https://withppl.com/mcp (100 tools). Full guide: https://withppl.com/agents","contact":{"url":"https://withppl.com/agents"},"termsOfService":"https://withppl.com/terms"},"servers":[{"url":"https://withppl.com/api"}],"security":[{"bearer":[]},{"oauth2":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Connect-flow token, personal API key, or OAuth access token"},"oauth2":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://withppl.com/oauth/authorize","tokenUrl":"https://withppl.com/oauth/token","refreshUrl":"https://withppl.com/oauth/token","scopes":{"agent:briefing":"ppl scope","agent:actions":"ppl scope","agent:search":"ppl scope","read:contacts":"ppl scope","write:contacts":"ppl scope","read:journal":"ppl scope","write:journal":"ppl scope","read:tasks":"ppl scope","write:tasks":"ppl scope","message:send":"ppl scope","message:read":"ppl scope","circles:read":"ppl scope","circles:write":"ppl scope"}}}}}},"paths":{"/agent/connect/request":{"post":{"operationId":"requestConnection","summary":"Start the one-approval connect flow (no auth). Returns approve_url for the human and poll_url for the agent.","tags":["connect"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_name":{"type":"string","description":"Your agent name"},"redirect_uri":{"type":"string","description":"Optional URL the human returns to after approving"}},"required":["client_name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/agent/connect/{id}/status":{"get":{"operationId":"connectionStatus","summary":"Poll a connect request. When approved, the first poll returns api_token exactly once.","tags":["connect"],"security":[],"parameters":[{"name":"id","in":"path","required":true,"description":"Connect request id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/agent/preview":{"get":{"operationId":"previewBriefing","summary":"Synthetic sample briefing, no auth. Show it before asking the human to connect.","tags":["agent"],"security":[],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/agent/briefing":{"get":{"operationId":"getBriefing","summary":"Daily briefing: birthdays, reconnect candidates, open tasks, reminders","tags":["agent"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/agent/next-action":{"get":{"operationId":"getNextAction","summary":"The single highest-leverage relationship action, with a drafted message","tags":["agent"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/agent/actions":{"get":{"operationId":"getSuggestedActions","summary":"Ranked suggested actions with scores, reasons, and deep links","tags":["agent"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/agent/ask":{"post":{"operationId":"askMemory","summary":"Ask a natural language question about the human's people","tags":["agent"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"question":{"type":"string","description":"The question, up to 500 characters"}},"required":["question"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/agent/inbox":{"get":{"operationId":"getAgentInbox","summary":"Claimable work queue for background agents","tags":["agent"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/search/semantic":{"get":{"operationId":"semanticSearch","summary":"Semantic search across contacts, notes, and journal (keyword fallback)","tags":["search"],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":255}},{"name":"limit","in":"query","schema":{"type":"integer","maximum":100}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/interactions/log":{"post":{"operationId":"logInteraction","summary":"Log an interaction; returns relationship impact (before and after status)","tags":["interactions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer","description":"Contact id"},"type":{"type":"string","enum":["email","meeting","call","message"]},"occurred_at":{"type":"string","format":"date-time"},"subject":{"type":"string","description":"Short subject"},"summary":{"type":"string","description":"What happened"}},"required":["contact_id","type"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/contacts/{contact}/digest":{"get":{"operationId":"getPersonDigest","summary":"Everything known about one person: summary, last interaction, open tasks, milestones","tags":["contacts"],"parameters":[{"name":"contact","in":"path","required":true,"description":"Contact id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/contacts/{contact}/timeline":{"get":{"operationId":"getContactTimeline","summary":"Chronological timeline for one person","tags":["contacts"],"parameters":[{"name":"contact","in":"path","required":true,"description":"Contact id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/contacts/{contact}/communication-style":{"get":{"operationId":"getCommunicationStyle","summary":"A contact's preferred channel, tone notes, and formality","tags":["contacts"],"parameters":[{"name":"contact","in":"path","required":true,"description":"Contact id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/contacts/check-duplicates":{"post":{"operationId":"checkDuplicates","summary":"Check whether a person already exists before creating them","tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"email":{"type":"string","description":"Email"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/account/voice-profile":{"get":{"operationId":"getVoiceProfile","summary":"The human's writing voice (tone, greeting, signoff); read before drafting messages","tags":["account"],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/contacts":{"get":{"operationId":"listContacts","summary":"List contacts","tags":["contacts"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size"},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page number"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createContact","summary":"Create a contact","tags":["contacts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"nickname":{"type":"string","description":"Nickname"},"gender_id":{"type":"integer","description":"Gender id (see describe_schema)"},"is_birthdate_known":{"type":"boolean"},"is_deceased":{"type":"boolean"},"is_deceased_date_known":{"type":"boolean"}},"required":["first_name"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/contacts/{id}":{"get":{"operationId":"getContact","summary":"Get one contact","tags":["contacts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"updateContact","summary":"Update a contact","tags":["contacts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","description":"First name"},"last_name":{"type":"string","description":"Last name"},"nickname":{"type":"string","description":"Nickname"},"gender_id":{"type":"integer","description":"Gender id (see describe_schema)"},"is_birthdate_known":{"type":"boolean"},"is_deceased":{"type":"boolean"},"is_deceased_date_known":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"deleteContact","summary":"Delete a contact","tags":["contacts"],"parameters":[{"name":"id","in":"path","required":true,"description":"Contact id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/notes":{"get":{"operationId":"listNotes","summary":"List notes","tags":["notes"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size"},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page number"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createNote","summary":"Create a note","tags":["notes"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer","description":"Contact id"},"body":{"type":"string","description":"Note text"},"is_favorited":{"type":"boolean"}},"required":["contact_id","body"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/notes/{id}":{"get":{"operationId":"getNote","summary":"Get one note","tags":["notes"],"parameters":[{"name":"id","in":"path","required":true,"description":"Note id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"updateNote","summary":"Update a note","tags":["notes"],"parameters":[{"name":"id","in":"path","required":true,"description":"Note id","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer","description":"Contact id"},"body":{"type":"string","description":"Note text"},"is_favorited":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"deleteNote","summary":"Delete a note","tags":["notes"],"parameters":[{"name":"id","in":"path","required":true,"description":"Note id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/tasks":{"get":{"operationId":"listTasks","summary":"List tasks","tags":["tasks"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size"},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page number"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createTask","summary":"Create a task","tags":["tasks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer","description":"Contact id (optional)"},"title":{"type":"string","description":"Task title"},"description":{"type":"string","description":"Details"},"completed":{"type":"boolean"}},"required":["title"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/tasks/{id}":{"get":{"operationId":"getTask","summary":"Get one task","tags":["tasks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Task id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"updateTask","summary":"Update a task","tags":["tasks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Task id","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer","description":"Contact id (optional)"},"title":{"type":"string","description":"Task title"},"description":{"type":"string","description":"Details"},"completed":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"deleteTask","summary":"Delete a task","tags":["tasks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Task id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/reminders":{"get":{"operationId":"listReminders","summary":"List reminders","tags":["reminders"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size"},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page number"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createReminder","summary":"Create a reminder","tags":["reminders"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer","description":"Contact id"},"title":{"type":"string","description":"Reminder title"},"initial_date":{"type":"string","format":"date"},"frequency_type":{"type":"string","enum":["one_time","week","month","year"]},"frequency_number":{"type":"integer"}},"required":["contact_id","title","initial_date","frequency_type","frequency_number"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/reminders/{id}":{"get":{"operationId":"getReminder","summary":"Get one reminder","tags":["reminders"],"parameters":[{"name":"id","in":"path","required":true,"description":"Reminder id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"updateReminder","summary":"Update a reminder","tags":["reminders"],"parameters":[{"name":"id","in":"path","required":true,"description":"Reminder id","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"contact_id":{"type":"integer","description":"Contact id"},"title":{"type":"string","description":"Reminder title"},"initial_date":{"type":"string","format":"date"},"frequency_type":{"type":"string","enum":["one_time","week","month","year"]},"frequency_number":{"type":"integer"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"deleteReminder","summary":"Delete a reminder","tags":["reminders"],"parameters":[{"name":"id","in":"path","required":true,"description":"Reminder id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/journal":{"get":{"operationId":"listJournal","summary":"List journal","tags":["journal"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size"},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page number"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createJournalEntry","summary":"Create a journalEntry","tags":["journal"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Entry title"},"post":{"type":"string","description":"Entry body"},"date":{"type":"string","format":"date"}},"required":["title","post"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/journal/{id}":{"get":{"operationId":"getJournalEntry","summary":"Get one journalEntry","tags":["journal"],"parameters":[{"name":"id","in":"path","required":true,"description":"JournalEntry id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"updateJournalEntry","summary":"Update a journalEntry","tags":["journal"],"parameters":[{"name":"id","in":"path","required":true,"description":"JournalEntry id","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","description":"Entry title"},"post":{"type":"string","description":"Entry body"},"date":{"type":"string","format":"date"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"deleteJournalEntry","summary":"Delete a journalEntry","tags":["journal"],"parameters":[{"name":"id","in":"path","required":true,"description":"JournalEntry id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/webhooks":{"get":{"operationId":"listWebhooks","summary":"List webhooks","tags":["webhooks"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","maximum":100},"description":"Page size"},{"name":"page","in":"query","schema":{"type":"integer"},"description":"Page number"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"operationId":"createWebhook","summary":"Create a webhook","tags":["webhooks"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS endpoint that receives events"},"events":{"type":"array","items":{"type":"string"}}},"required":["url","events"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/webhooks/{id}":{"get":{"operationId":"getWebhook","summary":"Get one webhook","tags":["webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id","schema":{"type":"integer"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"put":{"operationId":"updateWebhook","summary":"Update a webhook","tags":["webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id","schema":{"type":"integer"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","description":"HTTPS endpoint that receives events"},"events":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"operationId":"deleteWebhook","summary":"Delete a webhook","tags":["webhooks"],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook id","schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}