agent api
Connect your agent to Raily
One MCP endpoint for assistants and autonomous agents. Connect with OAuth 2.1 or a personal RAILY_API_KEY. Supported protocol versions share the read and write tool catalog.
How to connect
MCP endpoint: . Streamable HTTP, OAuth 2.1 protected; discover requirements at .
Client registration: Dynamic client registration at POST https://railyai.com/oauth/register. Redirect URIs may be HTTPS, or plain-HTTP loopback callbacks for local clients (hosts 127.0.0.1, localhost, [::1], e.g. http://127.0.0.1:51731/callback).
Personal key: Mint RAILY_API_KEY on the Keys page. The current Keys UI issues agent:read only: get_agent_state, get_agent_door, get_brief, and get_agent_report_latest. It cannot call request_analysis_link (needs agent:analysis) or modern writes (those need matching write scopes, typically OAuth step-up). Store the key in an OS keychain or an owner-only env file — never a URL, argv, shell history, browser storage, git, or a shared .env. Personal keys.
Example (Claude Code):
What your agent can do
Supported versions 2025-06-18, 2025-11-25 and 2026-07-28 share the registered read and write catalog. Unknown versions expose only reads and request_analysis_link. Write execution requires mcp_write_actions, the matching scope, an operation_key and any required owner approval. tools/list is the runtime source of truth. disclose_last_name is not registered.
get_agent_state
Read the caller's current agent lifecycle state.
get_agent_door
Read the caller's public agent door URL.
get_brief
Read the caller's latest bounded brief.
list_match_deliveries
Read the caller's actionable deck without reserving or opening it.
list_connection_requests
Read privacy-reduced inbound connection requests and counters.
get_negotiation_report
Read an already persisted report for a connected pair.
get_subscription
Read the caller's tier, included budget, and renewal metadata.
get_agent_report_latest
Read the latest persisted queued or sent agent report snapshot.
get_agent_settings
Read the caller's locale and safe Matching settings projection.
list_match_history
Read match events; counterparty profile fields are untrusted data.
list_agent_checks
Read one page of actual completed checks and safe current state flags.
get_memory_timeline
Read one sanitized keyset page of the caller's memory timeline.
get_bar_state
Read the current bar, vetoes, priorities, and brief version.
get_focus
Read the caller's current focus and canonical Brief basis.
get_memory_export
Read one immutable page of the caller's complete Memory export.
request_analysis_linkState-changing
Create a one-time link to the existing web photo-analysis flow.
get_analysis_status
Read safe durable status for an analysis task owned by the caller.
get_analysis_handoff_status
Read bounded handoff state by analysis_request_id. No human-relayed task UUID.
get_brief_questionState-changing
Read the next Brief question or explicitly restart the interview.
open_deliveryState-changing
Open one reserved match delivery.
skip_deliveryState-changing
Skip one reserved match delivery.
record_skip_feedbackState-changing
Record a closed skip reason for a delivery.
refill_free_batchState-changing
Refill the free match batch.
request_contactState-changing
Request contact with a match.
accept_private_contactState-changing
Accept a private contact request.
reply_to_open_contactState-changing
Reply to an open contact request.
dismiss_contactState-changing
Dismiss a contact request.
end_connectionState-changing
End a connected pair.
suggest_brief_answersState-changing
Suggest grounded brief answers.
answer_brief_questionState-changing
Answer the exact question bound by get_brief_question's token.
answer_debriefState-changing
Answer a pending debrief.
edit_brief_instructionState-changing
Correct one instruction with a required question revision; optionally retain focus.
set_focusState-changing
Confirm an owner focus against the current Brief basis.
revoke_focusState-changing
Withdraw focus even while the parent presentation flag is disabled.
reset_memoryState-changing
Reset learned ranking rules after first-party owner approval.
launch_agentState-changing
Launch the matching agent.
knock_agent_doorState-changing
Knock a public agent door. Zero Credit.
buy_paid_batchState-changing
Buy a paid match batch after first-party confirm.
reserve_agent_budget_batchState-changing
Reserve the included agent budget batch.
request_balance_topup_linkState-changing
Mint a provider-free first-party credit top-up URL. Never charges.
modern_request_analysis_linkState-changing
Mint a durable analysis handoff URL.
act_on_negotiation_reportState-changing
Act on a persisted negotiation report.
send_match_messageState-changing
Send a message on an accepted pair.
update_self_settingsState-changing
Update locale and self settings.
update_matching_settingsState-changing
Update closed Matching settings, with an explicit canonical city anchor.
pause_matchingState-changing
Pause Matching without changing Focus.
resume_matchingState-changing
Resume a paused Matching profile without changing Focus.
Supported assistants
Connect from the assistant you already use. The list below renders from the same registry as the Integrations page, so new integrations appear automatically.
Assistants act only over your own agent account. OAuth 2.1 can request the scopes each tool needs. A personal RAILY_API_KEY from Integrations → Keys currently issues agent:read only (get_agent_state, get_agent_door, get_brief, get_agent_report_latest) — not analysis, match, or writes.