{"openapi":"3.1.0","info":{"title":"Expert Sapiens Agent API","version":"2.0.0","description":"Machine-readable API for AI agents to discover, evaluate, and surface verified human experts on Expert Sapiens. Experts are credentialed professionals (lawyers, accountants, tax advisors, consultants, etc.) available for one-on-one consultations.","contact":{"name":"Expert Sapiens","url":"https://expertsapiens.com/en/about"}},"servers":[{"url":"https://expertsapiens.com","description":"Production"}],"paths":{"/api/agents/experts":{"get":{"operationId":"searchExperts","summary":"Search and filter experts","description":"Returns a paginated list of publicly visible, verified experts matching the given filters. Use this endpoint to find experts by professional category, location, language, or keyword. Rate limit: 60 req/min (unauthenticated, IP-keyed) or 300 req/min (Bearer token). Exceeding the limit returns HTTP 429 with a Retry-After header.","parameters":[{"name":"q","in":"query","description":"Keyword search across expert name, title, and tagline (case-insensitive, partial match).","schema":{"type":"string","example":"immigration attorney"}},{"name":"category","in":"query","description":"Filter by category slug. Valid slugs: legal, accounting, tax-advisory, business-consulting, finance, marketing, technology, immigration, healthcare, human-resources, intellectual-property, real-estate, english-tutor, language-tutor, professional-instructor.","schema":{"type":"string","example":"legal"}},{"name":"country","in":"query","description":"Filter by ISO 3166-1 alpha-2 country code.","schema":{"type":"string","example":"US"}},{"name":"city","in":"query","description":"Filter by city name (case-insensitive).","schema":{"type":"string","example":"Seoul"}},{"name":"language","in":"query","description":"Filter by language the expert speaks. Use BCP 47 codes (e.g. 'en', 'ko', 'ja', 'zh', 'fr', 'de').","schema":{"type":"string","example":"ko"}},{"name":"locale","in":"query","description":"Display locale for i18n titles. Affects which translated title is returned. Default: 'en'.","schema":{"type":"string","enum":["en","ko","ja","zh","fr","de"],"default":"en"}},{"name":"accepting","in":"query","description":"Set to '1' to return only experts currently accepting new clients.","schema":{"type":"string","enum":["1"]}},{"name":"sort","in":"query","description":"Sort order. 'rating' returns highest-rated first (default). 'newest' returns most recently listed first.","schema":{"type":"string","enum":["rating","newest"],"default":"rating"}},{"name":"page","in":"query","description":"Zero-based page number. Default: 0.","schema":{"type":"integer","minimum":0,"default":0}},{"name":"limit","in":"query","description":"Results per page. Max: 20. Default: 10.","schema":{"type":"integer","minimum":1,"maximum":20,"default":10}}],"responses":{"200":{"description":"Paginated expert search results.","content":{"application/json":{"schema":{"type":"object","properties":{"experts":{"type":"array","items":{"$ref":"#/components/schemas/ExpertSummary"}},"total":{"type":"integer","description":"Total matching experts."},"page":{"type":"integer"},"limit":{"type":"integer"},"has_more":{"type":"boolean"}}}}}},"500":{"description":"Database error."}}}},"/api/agents/experts/{slug}":{"get":{"operationId":"getExpert","summary":"Get full expert profile","description":"Returns complete structured profile for a single expert: bio, services with pricing, weekly availability schedule, and all public contact/social links. Use this after finding a candidate via searchExperts to get the detail needed to evaluate fit and present booking options. Rate limit: 120 req/min (unauthenticated, IP-keyed) or 600 req/min (Bearer token).","parameters":[{"name":"slug","in":"path","required":true,"description":"Expert's unique slug (from search results or profile URL).","schema":{"type":"string","example":"james-chae"}},{"name":"locale","in":"query","description":"Display locale for i18n fields (bio, title, tagline). Default: 'en'.","schema":{"type":"string","enum":["en","ko","ja","zh","fr","de"],"default":"en"}}],"responses":{"200":{"description":"Full expert profile.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExpertProfile"}}}},"404":{"description":"Expert not found or not publicly available."}}}},"/api/agents/experts/{slug}/availability":{"get":{"operationId":"getExpertAvailability","summary":"Get expert availability slots","description":"Returns the expert's recurring weekly availability schedule as time slots per day of week, plus their timezone and current availability status.","parameters":[{"name":"slug","in":"path","required":true,"description":"Expert's unique slug.","schema":{"type":"string"}}],"responses":{"200":{"description":"Availability schedule.","content":{"application/json":{"schema":{"type":"object","properties":{"slots":{"type":"array","items":{"type":"object","properties":{"day_of_week":{"type":"integer","minimum":0,"maximum":6,"description":"0 = Sunday, 6 = Saturday."},"start_time":{"type":"string","example":"09:00:00"},"end_time":{"type":"string","example":"17:00:00"}}}},"timezone":{"type":"string","nullable":true,"example":"Asia/Seoul"},"availability_status":{"type":"string","nullable":true,"enum":["open","limited","closed"]},"booking_buffer_minutes":{"type":"integer","nullable":true}}}}}}}}},"/api/agents/inquiries":{"post":{"operationId":"submitInquiry","summary":"Submit an inquiry to an expert","description":"Send a message to a specific expert on behalf of your user. The expert is notified by email and can reply directly. Requires an API key (Authorization: Bearer es_live_...).\n\nRate limit: 5 inquiries per API key per expert per 24 hours.","security":[{"AgentApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["expert_slug","requester_name","requester_email","message"],"properties":{"expert_slug":{"type":"string","description":"Unique slug of the expert to contact. Get this from searchExperts or getExpert.","example":"james-chae"},"requester_name":{"type":"string","maxLength":200,"description":"Full name of the person the agent is acting on behalf of.","example":"Sarah Kim"},"requester_email":{"type":"string","format":"email","description":"Email address for the expert to reply to.","example":"sarah@example.com"},"message":{"type":"string","maxLength":2000,"description":"The inquiry message. Be specific about what the user needs.","example":"Hi, I need help structuring a US-Korea cross-border acquisition. Can you advise on the tax implications?"},"context":{"type":"object","description":"Optional structured context from the agent (e.g. session metadata).","additionalProperties":true,"example":{"source":"my-agent-app","session_id":"sess_abc123"}}}}}}},"responses":{"201":{"description":"Inquiry submitted. Expert has been notified.","content":{"application/json":{"schema":{"type":"object","properties":{"inquiry_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending"]},"expert_profile_url":{"type":"string","format":"uri"},"booking_url":{"type":"string","format":"uri"},"email_sent":{"type":"boolean"},"created_at":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Validation error — see errors array in response."},"401":{"description":"Missing or invalid API key."},"404":{"description":"Expert not found or not publicly available."},"429":{"description":"Rate limit exceeded. Retry after 24 hours."}}}},"/api/agents/keys":{"get":{"operationId":"listApiKeys","summary":"List your API keys","description":"Returns all active (non-revoked) API keys for the logged-in user. Requires browser session auth.","responses":{"200":{"description":"List of active keys.","content":{"application/json":{"schema":{"type":"object","properties":{"keys":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_prefix":{"type":"string","description":"First 12 chars of the key for identification."},"created_at":{"type":"string","format":"date-time"},"last_used_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"401":{"description":"Not logged in."}}},"post":{"operationId":"createApiKey","summary":"Create a new API key","description":"Generates a new API key. The plaintext key is returned once in the response — store it securely as it cannot be retrieved again. Max 10 active keys per user. Requires browser session auth.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100,"description":"Human-readable label for this key.","example":"My Legal Assistant Agent"}}}}}},"responses":{"201":{"description":"Key created. The `key` field contains the plaintext — this is the only time it is returned.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"key_prefix":{"type":"string"},"key":{"type":"string","description":"Full plaintext API key — shown once only."},"warning":{"type":"string"},"created_at":{"type":"string","format":"date-time"}}}}}},"401":{"description":"Not logged in."},"409":{"description":"Key limit reached (max 10)."}}}},"/api/agents/keys/{id}":{"delete":{"operationId":"revokeApiKey","summary":"Revoke an API key","description":"Immediately revokes an API key. Any requests using the revoked key will receive 401. Requires browser session auth.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Key revoked."},"401":{"description":"Not logged in."},"403":{"description":"You do not own this key."},"404":{"description":"Key not found."},"409":{"description":"Key is already revoked."}}}}},"components":{"securitySchemes":{"AgentApiKey":{"type":"http","scheme":"bearer","bearerFormat":"es_live_..."}},"schemas":{"ExpertSummary":{"type":"object","description":"Condensed expert record returned by search.","properties":{"slug":{"type":"string","description":"Unique identifier for the expert."},"name":{"type":"string"},"title":{"type":"string","description":"Professional title (locale-aware)."},"tagline":{"type":"string","nullable":true},"avatar_url":{"type":"string","format":"uri"},"profile_url":{"type":"string","format":"uri","description":"Direct link to expert profile."},"booking_url":{"type":"string","format":"uri","description":"Deep link to expert booking section."},"categories":{"type":"array","items":{"type":"string"},"description":"Category slugs this expert belongs to."},"location":{"type":"object","properties":{"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"display":{"type":"string","nullable":true,"description":"Human-readable location string."}}},"rating":{"type":"number","nullable":true,"description":"Average star rating (0–5)."},"review_count":{"type":"integer"},"years_experience":{"type":"integer","nullable":true},"starting_price_usd":{"type":"number","nullable":true,"description":"Lowest service price in USD."},"languages_spoken":{"type":"array","items":{"type":"string"}},"tags":{"type":"array","items":{"type":"string"},"description":"Expertise tags."},"is_verified":{"type":"boolean"},"accepting_clients":{"type":"boolean","nullable":true},"availability_status":{"type":"string","nullable":true,"enum":["open","limited","closed"]}}},"ExpertProfile":{"type":"object","description":"Full expert profile with services and availability.","allOf":[{"$ref":"#/components/schemas/ExpertSummary"}],"properties":{"bio":{"type":"string","nullable":true,"description":"Expert biography (locale-aware)."},"cover_image_url":{"type":"string","format":"uri","nullable":true},"subcategory_slugs":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"display":{"type":"string","nullable":true},"city":{"type":"string","nullable":true},"state_code":{"type":"string","nullable":true},"country_code":{"type":"string","nullable":true},"timezone":{"type":"string","nullable":true,"example":"Asia/Seoul"},"coordinates":{"type":"object","nullable":true,"properties":{"lat":{"type":"number"},"lng":{"type":"number"}}}}},"credentials":{"type":"object","properties":{"is_verified":{"type":"boolean"},"is_featured":{"type":"boolean"},"years_experience":{"type":"integer","nullable":true}}},"ratings":{"type":"object","properties":{"average":{"type":"number","nullable":true},"review_count":{"type":"integer"}}},"availability":{"type":"object","properties":{"status":{"type":"string","nullable":true,"enum":["open","limited","closed"]},"accepting_clients":{"type":"boolean","nullable":true},"response_time_pledge":{"type":"string","nullable":true,"description":"Human-readable response time guarantee."},"schedule":{"type":"array","description":"Weekly recurring availability slots.","items":{"type":"object","properties":{"day":{"type":"string","example":"Monday"},"day_of_week":{"type":"integer","minimum":0,"maximum":6},"start_time":{"type":"string","example":"09:00:00"},"end_time":{"type":"string","example":"17:00:00"}}}}}},"pricing":{"type":"object","properties":{"starting_price_usd":{"type":"number","nullable":true}}},"services":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"description":{"type":"string","nullable":true},"price_usd":{"type":"number","nullable":true},"price_type":{"type":"string","enum":["fixed","hourly","custom"]},"duration_minutes":{"type":"integer","nullable":true}}}},"contact_methods":{"type":"object","description":"Available public contact/social channels. Only keys with values are present.","additionalProperties":{"type":"string"},"example":{"website":"https://example.com","linkedin":"https://linkedin.com/in/expert","kakaotalk_channel":"https://pf.kakao.com/_xyz"}},"ai_chat_available":{"type":"boolean","description":"Whether this expert has AI chat enabled for pre-session questions."}}}}}}