All Raysurfer functionality is available over plain HTTP. Every request uses POST with a JSON body (except health check and deletion).
Authentication
Include your API key in the Authorization header:
-H "Authorization: Bearer $RAYSURFER_API_KEY"
| Header | Description |
|---|
X-Raysurfer-Org-Id | Organization ID (team/enterprise) |
X-Raysurfer-Workspace-Id | Workspace ID (enterprise only) |
X-Raysurfer-Snips-Desired | "company" or "client" — scope of private snippets |
X-Raysurfer-Namespace | Custom namespace override |
Base URL
https://api.raysurfer.com
Retrieve
Search for code snippets
The primary retrieval endpoint. Returns cached code blocks ranked by semantic similarity, community votes, and error resilience.
curl -X POST https://api.raysurfer.com/api/retrieve/search \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Fetch GitHub trending repos",
"top_k": 5,
"min_verdict_score": 0.3,
"prefer_complete": false
}'
| Field | Type | Default | Description |
|---|
task | string | required | Natural language task description |
top_k | integer | 5 | Max results to return |
min_verdict_score | float | 0.3 | Minimum quality threshold (0–1) |
prefer_complete | boolean | false | Rank longer implementations higher |
input_schema | object | null | Optional input schema filter |
{
"matches": [
{
"code_block": {
"id": "abc123",
"name": "github_fetcher",
"description": "Fetches trending repos from GitHub",
"source": "import httpx\n\ndef fetch_trending():\n ...",
"entrypoint": "fetch_trending",
"language": "python",
"dependencies": ["httpx"]
},
"combined_score": 0.85,
"vector_score": 0.82,
"verdict_score": 0.90,
"error_resilience": 0.75,
"thumbs_up": 12,
"thumbs_down": 1,
"filename": "github_fetcher.py",
"language": "python",
"entrypoint": "fetch_trending",
"dependencies": ["httpx"]
}
],
"total_found": 3,
"cache_hit": false,
"search_namespaces": ["code_blocks", "task_patterns"]
}
Get few-shot examples
curl -X POST https://api.raysurfer.com/api/retrieve/few-shot-examples \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Parse CSV files",
"k": 3
}'
Get task patterns
curl -X POST https://api.raysurfer.com/api/retrieve/task-patterns \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "API integration",
"min_thumbs_up": 5,
"top_k": 20
}'
Query execution history
curl -X POST https://api.raysurfer.com/api/retrieve/executions \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code_block_id": "abc123",
"limit": 10
}'
Store
Upload code from an execution (recommended)
The simplest way to store code. Send the files your agent wrote and the task it was solving. The backend auto-detects language, entrypoint, and tags, then optionally votes on quality.
curl -X POST https://api.raysurfer.com/api/store/execution-result \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Parse CSV and generate a summary chart",
"files_written": [
{"path": "parser.py", "content": "import csv\n\ndef parse(path):\n ..."},
{"path": "chart.py", "content": "import matplotlib.pyplot as plt\n\ndef plot(data):\n ..."}
],
"succeeded": true,
"use_raysurfer_ai_voting": true,
"execution_logs": "Parsed 150 rows, chart saved to output.png"
}'
| Field | Type | Default | Description |
|---|
task | string | required | The task the agent was solving |
files_written | array | required | [{"path": "...", "content": "..."}] |
succeeded | boolean | required | Whether the task completed successfully |
use_raysurfer_ai_voting | boolean | true | Let Raysurfer AI vote on stored blocks. Ignored when user_vote is provided. |
user_vote | integer | null | User-provided vote: 1 = thumbs up, -1 = thumbs down. Skips AI voting. |
vote_source | string | null | "ai" or "human" — explicitly sets vote source. When omitted, user_vote defaults to "human", AI voting defaults to "ai". |
vote_count | integer | 1 | Number of votes to apply. Useful for pre-seeding community votes. |
execution_logs | string | null | Stdout/stderr for vote context |
run_url | string | null | Link to the finished run log |
Bulk upload with grading
Upload multiple prompts and files. The backend grades each file independently.
curl -X POST https://api.raysurfer.com/api/store/bulk-execution-result \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompts": ["Build a CLI tool", "Add CSV export"],
"files_written": [
{"path": "cli.py", "content": "import click\n..."},
{"path": "export.py", "content": "import csv\n..."}
],
"log_files": [
{"path": "logs/run.log", "content": "Task completed", "encoding": "utf-8"}
],
"use_raysurfer_ai_voting": true
}'
Store a code block (advanced)
Store a single code block with full metadata. Use this when you need fine-grained control over what’s stored.
curl -X POST https://api.raysurfer.com/api/store/code-block \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "GitHub User Fetcher",
"source": "import httpx\n\ndef fetch_user(username: str) -> dict:\n resp = httpx.get(f\"https://api.github.com/users/{username}\")\n return resp.json()",
"entrypoint": "fetch_user",
"language": "python",
"description": "Fetches user profile data from the GitHub API",
"tags": ["github", "api"],
"dependencies": ["httpx"],
"example_queries": ["get github user info", "fetch github profile"]
}'
Delete a snippet
curl -X POST https://api.raysurfer.com/api/snippets/delete \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"snippet_id": "CODE_BLOCK_ID"
}'
Check background task status
curl https://api.raysurfer.com/api/store/status/TASK_ID \
-H "Authorization: Bearer $RAYSURFER_API_KEY"
Vote
Record whether cached code was useful. This feeds back into the scoring system so better code surfaces higher.
curl -X POST https://api.raysurfer.com/api/store/cache-usage \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Fetch GitHub trending repos",
"code_block_id": "abc123",
"code_block_name": "github_fetcher",
"code_block_description": "Fetches trending repos from GitHub",
"succeeded": true
}'
Voting happens automatically when use_raysurfer_ai_voting is true (the default) in the store endpoints. You can also provide user_vote or user_votes to vote yourself — AI voting is skipped when user votes are provided. Use the vote endpoint directly only when you need manual control over cached code blocks.
Health check
curl https://api.raysurfer.com/health
{"status": "healthy", "redis": "connected"}
Error responses
All errors return a JSON body with a detail field:
{"detail": "Invalid API key"}
| Status | Meaning |
|---|
| 401 | Invalid or missing API key |
| 404 | Resource not found |
| 422 | Validation error (check request body) |
| 429 | Rate limit exceeded — check Retry-After header |
| 500 | Server error |
Full example: search then upload
A complete workflow — pull cached code, use it, then push results back:
# 1. Search for relevant cached code
curl -s -X POST https://api.raysurfer.com/api/retrieve/search \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"task": "Send a Slack notification", "top_k": 3}' | jq .
# 2. After your agent runs, upload the code it wrote
curl -s -X POST https://api.raysurfer.com/api/store/execution-result \
-H "Authorization: Bearer $RAYSURFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"task": "Send a Slack notification",
"files_written": [
{"path": "notify.py", "content": "import requests\n\ndef send_slack(msg):\n requests.post(WEBHOOK, json={\"text\": msg})"}
],
"succeeded": true
}' | jq .
