Fullcast

Fullcast Assistant API

The HTTP API behind the in-platform Fullcast Assistant (copilot) and the assistant-hosted Fullcast MCP Server. Covers chat sessions, message history, feedback, assistant configuration lifecycle, and a full OAuth 2.1 authorization-server surface (dynamic client registration, authorize, token, userinfo) used by external AI clients. Discovered as a live OpenAPI 3.1.0 document served at the API host root.

GitHub OpenAPI

Documentation

📖
APIReference
https://assistant.fullcast.io/docs
📖
Authentication
https://raw.githubusercontent.com/api-evangelist/fullcast/refs/heads/main/authentication/fullcast-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/fullcast/refs/heads/main/openapi/fullcast-assistant-openapi-original.json

Other Resources

🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/fullcast/refs/heads/main/errors/fullcast-problem-types.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/fullcast/refs/heads/main/data-model/fullcast-data-model.yml
🔗
Overlay
https://raw.githubusercontent.com/api-evangelist/fullcast/refs/heads/main/overlays/fullcast-assistant-overlay.yaml
🔗
APIsJSON
https://raw.githubusercontent.com/api-evangelist/fullcast/refs/heads/main/apis.yml

OpenAPI Specification

fullcast-assistant-openapi-original.json Raw ↑ 
{"openapi":"3.1.0","info":{"title":"Fullcast Assistant API","description":"API for Fullcast Assistant","version":"1.0.0"},"paths":{"/copilot-api/v1/chat":{"post":{"summary":"Chat","description":"Chat with the assistant","operationId":"chat_copilot_api_v1_chat_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}]}},"/copilot-api/v1/chat/messages":{"get":{"summary":"Get Messages","description":"Get messages for a chat session","operationId":"get_messages_copilot_api_v1_chat_messages_get","security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"session_id","in":"query","required":true,"schema":{"type":"string","description":"The session ID","title":"Session Id"},"description":"The session ID"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageList"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/copilot-api/v1/chat/feedback":{"post":{"summary":"Submit Feedback","description":"Submit feedback for a chat session","operationId":"submit_feedback_copilot_api_v1_chat_feedback_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeedbackRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}]}},"/copilot-api/v1/chat/stop":{"post":{"summary":"Stop Chat","description":"Stop an ongoing chat stream by setting the cancel event","operationId":"stop_chat_copilot_api_v1_chat_stop_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StopRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}]}},"/copilot-api/v1/chat/session":{"post":{"summary":"Create Session","description":"Create a new chat session or updates an existing session.","operationId":"create_session_copilot_api_v1_chat_session_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}]}},"/copilot-api/v1/chat/sessions":{"get":{"summary":"List Sessions","description":"List all active chat sessions for the current user","operationId":"list_sessions_copilot_api_v1_chat_sessions_get","security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","description":"Filter sessions by type. If unspecified, return all sessions","title":"Type"},"description":"Filter sessions by type. If unspecified, return all sessions"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/copilot-api/v1/chat/session/{session_id}":{"get":{"summary":"Get Session","description":"Get details of a specific chat session by ID","operationId":"get_session_copilot_api_v1_chat_session__session_id__get","security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"delete":{"summary":"Delete Session","description":"Delete a chat session by its ID","operationId":"delete_session_copilot_api_v1_chat_session__session_id__delete","security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/copilot-api/v1/chat/sessions_archived":{"get":{"summary":"List Archived Sessions","description":"List all archived chat sessions for the current user","operationId":"list_archived_sessions_copilot_api_v1_chat_sessions_archived_get","security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}],"parameters":[{"name":"type","in":"query","required":false,"schema":{"type":"string","description":"Filter sessions by type. If unspecified, return all sessions","title":"Type"},"description":"Filter sessions by type. If unspecified, return all sessions"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/copilot-api/v1/assistant":{"get":{"summary":"List Assistants","description":"List all assistants for the current user","operationId":"list_assistants_copilot_api_v1_assistant_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantList"}}}}},"security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}]},"put":{"summary":"Update Assistant","description":"Update an existing assistant","operationId":"update_assistant_copilot_api_v1_assistant_put","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assistant"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assistant"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"post":{"summary":"Create Assistant","description":"Create a new assistant","operationId":"create_assistant_copilot_api_v1_assistant_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assistant"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Assistant"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKeyCookie":[]},{"APIKeyHeader":[]}]},"delete":{"summary":"Deactivate Assistant","description":"Deactivate an existing assistant","operationId":"deactivate_assistant_copilot_api_v1_assistant_delete","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantDeletion"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"boolean","title":"Response Deactivate Assistant Copilot Api V1 Assistant Delete"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"summary":"Reactivate Assistant","description":"Reactivate an existing assistant","operationId":"reactivate_assistant_copilot_api_v1_assistant_patch","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AssistantDeletion"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"boolean","title":"Response Reactivate Assistant Copilot Api V1 Assistant Patch"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/oauth/register":{"post":{"tags":["oauth"],"summary":"Register Client","description":"OAuth 2.0 Dynamic Client Registration endpoint","operationId":"register_client_oauth_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/oauth/authorize":{"get":{"tags":["oauth"],"summary":"Authorize","description":"OAuth 2.0 Authorization endpoint","operationId":"authorize_oauth_authorize_get","parameters":[{"name":"response_type","in":"query","required":true,"schema":{"type":"string","title":"Response Type"}},{"name":"client_id","in":"query","required":true,"schema":{"type":"string","title":"Client Id"}},{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string","title":"Redirect Uri"}},{"name":"scope","in":"query","required":false,"schema":{"type":"string","default":"","title":"Scope"}},{"name":"state","in":"query","required":false,"schema":{"type":"string","title":"State"}},{"name":"code_challenge","in":"query","required":false,"schema":{"type":"string","title":"Code Challenge"}},{"name":"code_challenge_method","in":"query","required":false,"schema":{"type":"string","title":"Code Challenge Method"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/oauth/callback":{"options":{"tags":["oauth"],"summary":"Oauth Callback Options","description":"Handle OPTIONS preflight request for OAuth callback","operationId":"oauth_callback_options_oauth_callback_options","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}},"get":{"tags":["oauth"],"summary":"Oauth Callback","description":"Handle OAuth callback - supports both UUID (local) and Auth0 flows","operationId":"oauth_callback_oauth_callback_get","parameters":[{"name":"uuid","in":"query","required":false,"schema":{"type":"string","title":"Uuid"}},{"name":"code","in":"query","required":false,"schema":{"type":"string","title":"Code"}},{"name":"state","in":"query","required":false,"schema":{"type":"string","title":"State"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/oauth/token":{"post":{"tags":["oauth"],"summary":"Token Exchange","description":"OAuth 2.0 Token endpoint","operationId":"token_exchange_oauth_token_post","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/Body_token_exchange_oauth_token_post"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/oauth/userinfo":{"get":{"tags":["oauth"],"summary":"Userinfo","description":"OAuth 2.0 UserInfo endpoint - retrieves session from shared cache using UUID token","operationId":"userinfo_oauth_userinfo_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/copilot-api/v1/ping":{"get":{"summary":"Ping","operationId":"ping_copilot_api_v1_ping_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-authorization-server":{"get":{"summary":"Discovery","description":"OAuth 2.0 Authorization Server Metadata endpoint","operationId":"discovery__well_known_oauth_authorization_server_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"summary":"Protected Resource Metadata","description":"OAuth 2.0 Protected Resource Metadata endpoint","operationId":"protected_resource_metadata__well_known_oauth_protected_resource_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/mcp_info":{"get":{"summary":"Mcp Info","description":"Get MCP server information","operationId":"mcp_info_mcp_info_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}}},"components":{"schemas":{"Assistant":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name","description":"Name of the assistant"},"config":{"$ref":"#/components/schemas/AssistantConfig"},"metadata":{"anyOf":[{"$ref":"#/components/schemas/Metadata"},{"type":"null"}]}},"type":"object","required":["name","config","metadata"],"title":"Assistant"},"AssistantConfig":{"properties":{"provider":{"type":"string","title":"Provider","description":"Provider of the assistant"},"type":{"type":"string","title":"Type","description":"type of the assistant"},"model":{"type":"string","title":"Model","description":"Model used by the assistant"},"table_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Table Name","description":"Table name for the assistant"}},"type":"object","required":["provider","type","model"],"title":"AssistantConfig"},"AssistantDeletion":{"properties":{"id":{"type":"string","format":"uuid","title":"Id","description":"ID of the assistant to delete"}},"type":"object","required":["id"],"title":"AssistantDeletion"},"AssistantList":{"properties":{"assistants":{"items":{"$ref":"#/components/schemas/Assistant"},"type":"array","title":"Assistants","description":"List of assistants","default":[]}},"type":"object","title":"AssistantList"},"Body_token_exchange_oauth_token_post":{"properties":{"grant_type":{"type":"string","title":"Grant Type"},"code":{"type":"string","title":"Code"},"redirect_uri":{"type":"string","title":"Redirect Uri"},"client_id":{"type":"string","title":"Client Id"},"client_secret":{"type":"string","title":"Client Secret"},"code_verifier":{"type":"string","title":"Code Verifier"}},"type":"object","required":["grant_type","code","redirect_uri","client_id"],"title":"Body_token_exchange_oauth_token_post"},"ChatRequest":{"properties":{"session_id":{"type":"string","title":"Session Id"},"message":{"$ref":"#/components/schemas/Message"},"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"},"web_search_access":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Web Search Access","default":false}},"type":"object","required":["session_id","message"],"title":"ChatRequest"},"ClientRegistrationRequest":{"properties":{"redirect_uris":{"items":{"type":"string","minLength":1,"format":"uri"},"type":"array","title":"Redirect Uris"},"client_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Name"},"client_uri":{"anyOf":[{"type":"string","minLength":1,"format":"uri"},{"type":"null"}],"title":"Client Uri"},"logo_uri":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Logo Uri"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"},"contacts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Contacts"},"tos_uri":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Tos Uri"},"policy_uri":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Policy Uri"},"jwks_uri":{"anyOf":[{"type":"string","maxLength":2083,"minLength":1,"format":"uri"},{"type":"null"}],"title":"Jwks Uri"},"software_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Software Id"},"software_version":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Software Version"}},"type":"object","required":["redirect_uris"],"title":"ClientRegistrationRequest","description":"OAuth 2.0 Dynamic Client Registration Request (RFC 7591)"},"ClientRegistrationResponse":{"properties":{"client_id":{"type":"string","title":"Client Id"},"client_secret":{"type":"string","title":"Client Secret"},"client_id_issued_at":{"type":"integer","title":"Client Id Issued At"},"client_secret_expires_at":{"type":"integer","title":"Client Secret Expires At","default":0},"redirect_uris":{"items":{"type":"string"},"type":"array","title":"Redirect Uris"},"client_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Name"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"}},"type":"object","required":["client_id","client_secret","client_id_issued_at","redirect_uris"],"title":"ClientRegistrationResponse","description":"OAuth 2.0 Dynamic Client Registration Response (RFC 7591)"},"FeedbackRequest":{"properties":{"message_id":{"type":"string","title":"Message Id"},"feedback":{"type":"integer","title":"Feedback"},"feedback_comment":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Feedback Comment"},"support_ticket":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Support Ticket","default":false}},"type":"object","required":["message_id","feedback"],"title":"FeedbackRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Message":{"properties":{"role":{"type":"string","title":"Role","default":"user"},"content":{"type":"string","title":"Content"},"blocks":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Blocks"},"message_id":{"type":"string","title":"Message Id"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"masked_content":{"anyOf":[{"items":{"additionalProperties":true,"type":"object"},"type":"array"},{"type":"null"}],"title":"Masked Content"}},"type":"object","required":["content"],"title":"Message"},"MessageList":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/Message"},"type":"array","title":"Messages"}},"type":"object","required":["messages"],"title":"MessageList"},"Metadata":{"properties":{"title":{"type":"string","title":"Title"},"description":{"type":"string","title":"Description"},"icon":{"type":"string","title":"Icon"},"prompts":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Prompts"},"num_history_messages":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Num History Messages","default":0}},"type":"object","required":["title","description","icon","prompts"],"title":"Metadata"},"SessionRequest":{"properties":{"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id"},"assistant_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Assistant Id"},"browser_details":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Browser Details"},"current_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Current Url"},"renderLastFiveMessage":{"anyOf":[{"items":{},"type":"array"},{"type":"null"}],"title":"Renderlastfivemessage"},"planId":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Planid"},"planName":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Planname"},"pin_flag":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Pin Flag"},"type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Type"},"module":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Module"}},"type":"object","title":"SessionRequest"},"SessionResponse":{"properties":{"session":{"$ref":"#/components/schemas/UserSession"}},"type":"object","required":["session"],"title":"SessionResponse"},"StopRequest":{"properties":{"session_id":{"type":"string","title":"Session Id"}},"type":"object","required":["session_id"],"title":"StopRequest"},"TokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token"},"jwe_access_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Jwe Access Token"},"token_type":{"type":"string","title":"Token Type","default":"Bearer"},"expires_in":{"type":"integer","title":"Expires In"},"refresh_token":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Refresh Token"},"scope":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Scope"}},"type":"object","required":["access_token","expires_in"],"title":"TokenResponse","description":"OAuth 2.0 Token Response with both JWT and JWE tokens"},"UserSession":{"properties":{"id":{"type":"string","title":"Id"},"title":{"type":"string","title":"Title","default":""},"assistant_id":{"type":"string","title":"Assistant Id"},"user_id":{"type":"string","title":"User Id"},"tenant_id":{"type":"string","title":"Tenant Id"},"data":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Data"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"pin_flag":{"type":"boolean","title":"Pin Flag","default":false}},"type":"object","required":["assistant_id","user_id","tenant_id"],"title":"UserSession"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"APIKeyCookie":{"type":"apiKey","in":"cookie","name":"token"},"APIKeyHeader":{"type":"apiKey","in":"header","name":"csrf_token"}}}}