# Prompts

## Process a prompt request

> Processes a user prompt and returns an AI-generated response. The request must contain a valid API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"ProcessPromptBodyDTO":{"type":"object","properties":{"prompt":{"type":"string","description":"The question that the user sends to the AI agent"},"tokenTrackingId":{"type":"string","description":"The ID of the token tracking"}},"required":["prompt"]},"ProcessPromptResponseDTO":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed"],"description":"Response status"},"totalTokens":{"type":"number","description":"Total number of tokens used for the request","nullable":true},"response":{"type":"string","description":"The AI-generated response to the user prompt","nullable":true},"error":{"type":"string","description":"Response error","nullable":true}},"required":["status","totalTokens","response","error"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/prompts":{"post":{"description":"Processes a user prompt and returns an AI-generated response. The request must contain a valid API key.","operationId":"ExternalApiPromptsController_processPrompt","parameters":[],"requestBody":{"required":true,"description":"Provide the prompt text to process.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessPromptBodyDTO"}}}},"responses":{"200":{"description":"Successfully processed the prompt and returned a response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProcessPromptResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Process a prompt request","tags":["Prompts","Agent API Key"]}}}}
```

## Create a prompt request

> Creates a user prompt and returns an ID. The request must contain a valid API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"CreatePromptBodyDTO":{"type":"object","properties":{"prompt":{"type":"string","description":"The question that the user sends to the AI agent"},"tokenTrackingId":{"type":"string","description":"The ID of the token tracking"}},"required":["prompt"]},"CreatePromptResponseDTO":{"type":"object","properties":{"promptId":{"type":"string","description":"The ID of the prompt"}},"required":["promptId"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/prompts/async":{"post":{"description":"Creates a user prompt and returns an ID. The request must contain a valid API key.","operationId":"ExternalApiPromptsController_createPrompt","parameters":[],"requestBody":{"required":true,"description":"Provide the prompt text to process.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePromptBodyDTO"}}}},"responses":{"200":{"description":"Successfully created the prompt and returned an ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePromptResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Create a prompt request","tags":["Prompts","Agent API Key"]}}}}
```

## Get a response on prompt request

> Returns a response on a user prompt by ID. The request must contain a valid API key.

```json
{"openapi":"3.0.0","info":{"title":"AI Agent API","version":"1.0.0"},"servers":[{"url":"https://api.raia2.com","description":"Production server"}],"security":[{"Agent-Secret-Key":[]}],"components":{"securitySchemes":{"Agent-Secret-Key":{"type":"apiKey","in":"header","name":"Agent-Secret-Key","description":"Custom authentication header"}},"schemas":{"GetResponseOnPromptResponseDTO":{"type":"object","properties":{"status":{"type":"string","enum":["pending","completed","failed"],"description":"Response status"},"totalTokens":{"type":"number","description":"Total number of tokens used for the request","nullable":true},"response":{"type":"string","description":"The AI-generated response to the user prompt","nullable":true},"error":{"type":"string","description":"Response error","nullable":true}},"required":["status","totalTokens","response","error"]},"ForbiddenErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":403},"name":{"type":"object","default":"FORBIDDEN_ERROR"},"message":{"type":"string","default":"INVALID_CREDENTIALS"},"details":{"type":"array","items":{"type":"object"}}},"required":["status","name","message","details"]},"InternalServerErrorDTO":{"type":"object","properties":{"status":{"type":"number","default":500},"message":{"type":"string","default":"Internal Server Error"}},"required":["status","message"]}}},"paths":{"/external/prompts/{id}/response-on":{"get":{"description":"Returns a response on a user prompt by ID. The request must contain a valid API key.","operationId":"ExternalApiPromptsController_getResponseOnPrompt","parameters":[{"name":"id","required":true,"in":"path","description":"Provide the prompt ID to process.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successfully returned a response on the prompt. Returns null if the prompt is not ready.","schema":{"oneOf":[{"$ref":"#/components/schemas/GetResponseOnPromptResponseDTO"},{"type":"null"}]},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetResponseOnPromptResponseDTO"}}}},"403":{"description":"Invalid API key or secret key. Ensure that you are using a valid authentication key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ForbiddenErrorDTO"}}}},"500":{"description":"Unexpected error occurred while processing the request. Please try again later.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InternalServerErrorDTO"}}}}},"summary":"Get a response on prompt request","tags":["Prompts","Agent API Key"]}}}}
```