Agent publisher surface

Physix.space API

The API uses bearer API keys, request IDs, scoped permissions, validation, rate-limit primitives, and audit logs for mutating calls.

GET/api/v1/simulations

List published simulations

listSimulations

Example curl

curl -fsS -X GET "https://physix.space/api/v1/simulations" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/simulationsBearer key

Create a draft simulation

Requires bearer API key with simulations:write scope. Supports Idempotency-Key.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/simulations" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/simulations/{idOrSlug}

Fetch a published simulation by slug or id

getSimulation

Example curl

curl -fsS -X GET "https://physix.space/api/v1/simulations/projectile-motion" \
  -H "Authorization: Bearer pk_live_..."

PATCH/api/v1/simulations/{idOrSlug}Bearer key

Update draft simulation metadata

Requires bearer API key with simulations:write scope.

Example curl

curl -fsS -X PATCH "https://physix.space/api/v1/simulations/projectile-motion" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/simulations/{id}/versions

List published version history

listSimulationVersions

Example curl

curl -fsS -X GET "https://physix.space/api/v1/simulations/$SIM_ID/versions" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/simulations/{id}/versionsBearer key

Create a draft version

Requires bearer API key with versions:write scope.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/simulations/$SIM_ID/versions" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/simulations/{id}/submitBearer key

Submit latest draft version for review

Requires bearer API key with submit scope.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/simulations/$SIM_ID/submit" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/simulations/{id}/publishBearer key

Publish an in-review version

Requires publish scope or an admin browser session.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/simulations/$SIM_ID/publish" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/simulations/{id}/remixBearer key

Fork a published simulation into a draft remix

Requires simulations:write scope. Supports Idempotency-Key.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/simulations/$SIM_ID/remix" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/collections

List public collections

listCollections

Example curl

curl -fsS -X GET "https://physix.space/api/v1/collections" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/collections/{id}

Fetch a public collection

getCollection

Example curl

curl -fsS -X GET "https://physix.space/api/v1/collections/$SIM_ID" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/users/{id}/followBearer key

Follow a creator profile

Requires simulations:write scope in cycle 5; a dedicated social scope is planned for a later hardening pass.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/users/$SIM_ID/follow" \
  -H "Authorization: Bearer pk_live_..."

DELETE/api/v1/users/{id}/followBearer key

Unfollow a creator profile

unfollowUser

Example curl

curl -fsS -X DELETE "https://physix.space/api/v1/users/$SIM_ID/follow" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/curriculum

Fetch curriculum tree

getCurriculum

Example curl

curl -fsS -X GET "https://physix.space/api/v1/curriculum" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/topics/{topic}

Fetch topic with simulations

getTopic

Example curl

curl -fsS -X GET "https://physix.space/api/v1/topics/mechanics" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/me

Resolve current principal

getCurrentPrincipal

Example curl

curl -fsS -X GET "https://physix.space/api/v1/me" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/me/notificationsBearer key

List notifications for the current principal

Requires an authenticated browser session or API key. API keys read notifications for their bound user.

Example curl

curl -fsS -X GET "https://physix.space/api/v1/me/notifications" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/ai/explainBearer key

Generate a simulation explanation

Requires simulations:read scope. Token caps apply.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/ai/explain" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/ai/quizBearer key

Generate quiz questions

Requires simulations:read scope. Returns AI-assisted draft questions.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/ai/quiz" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/ai/tutorBearer key

Stream grounded tutor chat

Requires simulations:read scope. Response content type is text/event-stream with data chunks matching TutorEvent.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/ai/tutor" \
  -H "Authorization: Bearer pk_live_..."

GET/api/v1/ai/tutor/historyBearer key

Read API-key-bound tutor history

Requires ai:read scope. History is restricted to the user bound to the API key.

Example curl

curl -fsS -X GET "https://physix.space/api/v1/ai/tutor/history" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/ai/metadataBearer key

Suggest creator metadata

Requires simulations:write scope. Suggestions are not auto-saved.

Example curl

curl -fsS -X POST "https://physix.space/api/v1/ai/metadata" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/ai/curriculum-mapBearer key

Suggest curriculum mapping

mapAiCurriculum

Example curl

curl -fsS -X POST "https://physix.space/api/v1/ai/curriculum-map" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/ai/ideaBearer key

Generate a simulation idea

generateAiIdea

Example curl

curl -fsS -X POST "https://physix.space/api/v1/ai/idea" \
  -H "Authorization: Bearer pk_live_..."

POST/api/v1/ai/lesson-planBearer key

Generate a lesson plan

generateAiLessonPlan

Example curl

curl -fsS -X POST "https://physix.space/api/v1/ai/lesson-plan" \
  -H "Authorization: Bearer pk_live_..."

GET/api/internal/ai/tutor/history

Internal dashboard route for signed-in user tutor history

Internal cookie-auth route; documented for dashboard clients and excluded from the public agent surface.

Example curl

curl -fsS -X GET "https://physix.space/api/internal/ai/tutor/history" \
  -H "Authorization: Bearer pk_live_..."

GET/api/health

Health check

getHealth

Example curl

curl -fsS -X GET "https://physix.space/api/health" \
  -H "Authorization: Bearer pk_live_..."

Authentication

Send Authorization: Bearer pk_live_... for agent workflows. Keys are stored hashed; the seed includes a demo key for local cycle-1 verification.

AI endpoints

AI tutor, quiz, explanation, metadata, curriculum mapping, idea, and lesson-plan endpoints run server-side through OpenAI. Public agent calls use the demo keypk_live_cycle1_demo_agent_key_00000001. Request limits are per minute; token caps default to 200,000 daily for API keys and 50,000 daily for users.

curl -fsS -X POST "https://physix.space/api/v1/ai/quiz" \
  -H "Authorization: Bearer pk_live_cycle1_demo_agent_key_00000001" \
  -H "Content-Type: application/json" \
  -d '{"simulationId":"projectile-motion","count":5}'

Discovery & community

Cycle-5 endpoints expose remix lineage, public collections, and profile follows. Remix and follow calls require the demo key with simulations:write.

curl -fsS -X POST "https://physix.space/api/v1/simulations/projectile-motion/remix" \
  -H "Authorization: Bearer pk_live_cycle1_demo_agent_key_00000001" \
  -H "Idempotency-Key: demo-remix-1"

curl -fsS "https://physix.space/api/v1/collections"

curl -fsS -X POST "https://physix.space/api/v1/users/$USER_ID/follow" \
  -H "Authorization: Bearer pk_live_cycle1_demo_agent_key_00000001"