Integration model
rybot is designed to sit behind your product's authenticated experience. Your server identifies the user, creates a short-lived rybot session, and gives only that session token to the client.
Your service maps its users and organizations into scoped rybot sessions.
Long-running work reports progress and results through an event stream.
ryco.io provisions service access after the integration scope is approved.
Authentication
Keep the partner service token on your server. Exchange it for a user-scoped session token, then send that session token as a Bearer credential on user-facing API requests.
Your serverHolds the managed service credential
rybot sessionScopes access to one external user
Your clientUses only the short-lived session token
There is no public key generator. Request access to receive credentials and environment details from ryco.io.
Quickstart
curl -X POST https://api.ryco.io/v2/sessions \
-H "Content-Type: application/json" \
-H "x-rybot-service-token: $RYBOT_SERVICE_TOKEN" \
-d '{
"externalUserId": "user_123",
"externalOrgId": "school_456",
"gradeLevel": "6",
"subjectArea": "Science"
}'curl -X POST https://api.ryco.io/v2/threads/:threadId/messages \
-H "Authorization: Bearer $RYBOT_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "Compare the three uploaded readings and explain the key differences.",
"web": "auto"
}'Public capabilities
rybot's public API covers the full conversation lifecycle—from grounded research and generated media to delivery, voice, and useful context between sessions.
Ground answers in current web research and stream source citations with the response.
Create original illustrations, diagrams, classroom visuals, and coordinated image sets.
Produce researched, illustrated, validated PDFs and revise them through follow-up messages.
Turn data, functions, and quantitative prompts into rendered, source-aware visuals.
Upload source files for analysis, download generated media, and create revocable public shares.
Create speech audio, stream it directly, or run a low-latency realtime conversation.
Carry useful preferences forward and generate contextual ways to continue the work.
Persist conversations, stream progress, inspect status, cancel work, and retry failures.
Ground the answer in current sources.
Give rybot access to up-to-date web information, then stream citations alongside the response so your product can show the source trail as it arrives.
/v2/threads/:threadId/messagesPut the research question in content and setwebto control search for that message.
autoLet rybot use search when the prompt needs current or sourced information.
requiredRequire a web search for this message.
offAnswer without using web search for this message.
curl -X POST https://api.ryco.io/v2/threads/:threadId/messages \
-H "Authorization: Bearer $RYBOT_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "Find the latest evidence on later school start times and cite the sources.",
"web": "required"
}'Search progress and citations are separate events.
Listen on /v2/runs/:runId/events. Tool events report the search lifecycle; citation events carry each source URL and title.
tool_call- Uses
name: "web_search"with started, completed, or failed status. citation- Returns a source URL, title, and optional text range.
event: tool_call
data: {"type":"tool_call","name":"web_search","status":"started"}
event: citation
data: {"type":"citation","url":"https://example.org/research","title":"Research title"}Citations are also retained on the completed assistant message, so clients can render sources during the run and after the conversation is reloaded.
Create the visual in the conversation.
Generate original illustrations, diagrams, classroom visuals, and coordinated image sets through the same message API used for every rybot conversation.
/v2/threads/:threadId/messagesDescribe the image in content and set theimagefield to control how rybot handles the request.
autoLet rybot infer when a prompt calls for an original image.
requiredRequire image generation for this message.
offKeep image generation unavailable for this message.
curl -X POST https://api.ryco.io/v2/threads/:threadId/messages \
-H "Authorization: Bearer $RYBOT_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "Create a labeled watercolor diagram of the water cycle for grade 5.",
"image": "required"
}'Images arrive as run events.
The message response returns a runId. Subscribe to/v2/runs/:runId/events and listen for two image event types.
image_generation- Reports started, completed, or failed status.
generated_image- Returns the stored image metadata and access path.
event: image_generation
data: {"type":"image_generation","status":"started","index":0,"total":2,"label":"Water cycle"}
event: generated_image
data: {"type":"generated_image","mediaId":"media_123","accessPath":"/v2/media/media_123","mimeType":"image/png","index":0,"total":2}Ask for multiple visuals in one prompt to receive a coordinated set. Each image event includes index, total, and an optional label so your interface can place results as they finish.
Turn the request into a finished document.
Create polished PDFs from a prompt and optional attachments. rybot can research the subject, create supporting visuals, render the document, and validate the file before delivery.
/v2/threads/:threadId/messagesAsk explicitly for a PDF in content. Setwebto required when the document needs current, sourced research.
preparingPlan the document and gather any required research.
creating_visualsCreate illustrations requested by the document plan.
renderingAssemble the content and visual system into a PDF.
validatingVerify the generated file before returning it.
curl -X POST https://api.ryco.io/v2/threads/:threadId/messages \
-H "Authorization: Bearer $RYBOT_SESSION_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"content": "Create a four-page PDF guide to the water cycle for grade 5 with diagrams and a sources page.",
"web": "required"
}'Show progress before the file arrives.
PDF lifecycle events expose the active phase. The generated file event returns an attachment with its filename, media type, and access path.
pdf_generation- Reports started, completed, or failed status across 4 phases.
generated_file- Returns the completed PDF as a message attachment.
event: pdf_generation
data: {"type":"pdf_generation","status":"started","phase":"preparing","fileName":"water-cycle-guide.pdf"}
event: generated_file
data: {"type":"generated_file","attachment":{"fileName":"water-cycle-guide.pdf","mimeType":"application/pdf","accessPath":"/v2/media/media_456"}}
event: pdf_generation
data: {"type":"pdf_generation","status":"completed","phase":"validating"}Generated PDFs are stored as private media. Use the media endpoint to download them, create a revocable public share when needed, or continue in the same thread to request a revision.
HTTP endpoints
Explore every supported public endpoint for sessions, messages, streaming runs, generated media, file sharing, voice, realtime, memory, and suggestions.
Sessions
1/v2/sessionsExchange a managed service credential for a scoped user session.
service tokenThreads & messages
7/v2/threadsList the authenticated user's conversation threads.
session token/v2/threadsCreate a conversation thread.
session token/v2/threads/:threadIdUpdate a thread title or lifecycle status.
session token/v2/threads/:threadIdDelete a conversation thread.
session token/v2/threads/:threadId/messagesPage through messages in a thread.
session token/v2/threads/:threadId/messagesSend a message and start an asynchronous rybot run.
session token/v2/thread-titleCreate a concise title for conversation content.
session tokenRuns & streaming
4/v2/runs/:runId/eventsStream run progress and results as server-sent events.
session token/v2/runs/:runIdRead the current state of a run.
session token/v2/runs/:runId/cancelCancel an active run.
session token/v2/runs/:runId/retryRetry a failed run without duplicating its user message.
session tokenFiles & sharing
4/v2/uploadsUpload source material for analysis within a session.
session token/v2/media/:mediaIdDownload private media owned by the authenticated user.
session token/v2/media/:mediaId/shareCreate a revocable public share for a media file.
session token/v2/media/:mediaId/shareRevoke a media file's public share.
session tokenVoice & realtime
5/v2/audio/speechCreate speech audio for supported response text.
session token/v2/audio/speech/streamStream speech audio as it is produced.
session token/v2/realtime/sessionsCreate a short-lived realtime voice session.
session token/v2/realtime/turnsPersist completed realtime conversation turns.
session token/v2/realtime/sessions/:sessionId/endFinish a realtime session and its server-side work.
session tokenPersonalization
5/v2/suggestionsReturn contextual ways to continue a conversation.
session token/v2/suggestions/feedbackRecord feedback on a contextual suggestion.
session token/v2/memoriesList the authenticated user's saved context.
session token/v2/memories/:memoryIdUpdate or hide a saved memory.
session token/v2/memories/:memoryIdDelete a saved memory.
session tokenSystem
1/healthCheck API availability and deployed version.
public