---
title: "Evaluation Sessions"
url: "https://real-estate-agency.apim.eu/apis/evaluation-sessions/versions/b3c12e5c-39d5-45ea-824c-783ae0f56765"
---

# Evaluation Sessions

OpenAPI specification document.

```json
{"openapi":"3.0.3","info":{"title":"Evaluation Sessions","version":"1.0.0","description":"Schedules individual and group evaluation sessions, manages confirmations\nand cancellations, and collects feedback after the session.\n\nThe API supports two models: **fixed sessions**, to which you invite\nrequesters, and **availability windows**, from which requesters pick their\nown slot. Both can be mixed per agent.\n","contact":{"name":"API Support - Nexora AI","email":"api-support@nexora.example"},"license":{"name":"For demonstration purposes only"}},"servers":[{"url":"https://api.nexora.example/v1","description":"Production"},{"url":"https://sandbox.api.nexora.example/v1","description":"Sandbox"}],"tags":[{"name":"Sessions"},{"name":"Availability"},{"name":"Feedback"}],"security":[{"apiKey":[]}],"paths":{"/sessions":{"get":{"tags":["Sessions"],"summary":"List evaluation sessions","operationId":"listSessions","parameters":[{"name":"agent_id","in":"query","schema":{"type":"string","example":"agt_8f2c1a"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/SessionStatus"}}],"responses":{"200":{"description":"Results list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Session"}},"page":{"$ref":"#/components/schemas/Page"}}}}}},"401":{"$ref":"#/components/responses/NotAuthenticated"}}},"post":{"tags":["Sessions"],"summary":"Create an evaluation session","operationId":"createSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionInput"},"examples":{"single":{"summary":"Individual evaluation","value":{"agent_id":"agt_8f2c1a","type":"individual","start":"2026-09-03T16:00:00+02:00","duration_minutes":30,"location_or_link":"https://meet.nexora.example/eval-8f2c1a"}},"group":{"summary":"Group evaluation with twelve slots","value":{"agent_id":"agt_8f2c1a","type":"group","start":"2026-09-05T11:00:00+02:00","duration_minutes":60,"slots":12}}}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"409":{"description":"Time conflict with an existing session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"code":"conflict","message":"There is already a session for this agent at that time.","details":[{"field":"start","reason":"overlap"}]}}}}}}},"/sessions/{sessionId}":{"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","example":"sess_9a44"}}],"get":{"tags":["Sessions"],"summary":"Retrieve an evaluation session","operationId":"getSession","responses":{"200":{"description":"Session","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Sessions"],"summary":"Reschedule or update a session","description":"When the start time changes, all confirmed attendees are notified automatically.","operationId":"rescheduleSession","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionInput"},"example":{"start":"2026-09-03T17:30:00+02:00"}}}},"responses":{"200":{"description":"Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"404":{"$ref":"#/components/responses/NotFound"}}},"delete":{"tags":["Sessions"],"summary":"Cancel a session","operationId":"cancelSession","responses":{"204":{"description":"Cancelled; attendees have been notified"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/sessions/{sessionId}/confirmations":{"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","example":"sess_9a44"}}],"get":{"tags":["Sessions"],"summary":"List confirmations for a session","operationId":"listConfirmations","responses":{"200":{"description":"Attendee list","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Confirmation"}},"open_slots":{"type":"integer","example":4}}}}}}}},"post":{"tags":["Sessions"],"summary":"Confirm a requester's attendance","description":"If the session is fully booked, the requester is placed on the waitlist instead.","operationId":"createConfirmation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requester_id"],"properties":{"requester_id":{"type":"string","example":"req_71ab"},"attendees":{"type":"integer","minimum":0,"maximum":3,"default":0}}}}}},"responses":{"201":{"description":"Confirmation recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Confirmation"}}}},"409":{"description":"Requester has already confirmed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/availability":{"get":{"tags":["Availability"],"summary":"Query open time slots","description":"Returns bookable slots for an agent, derived from the responsible\nreviewer's stored working hours minus sessions already booked.\n","operationId":"getAvailability","parameters":[{"name":"agent_id","in":"query","required":true,"schema":{"type":"string","example":"agt_8f2c1a"}},{"name":"from","in":"query","required":true,"schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":true,"schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"Time slots","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/TimeSlot"}}}},"example":{"data":[{"start":"2026-09-03T16:00:00+02:00","end":"2026-09-03T16:30:00+02:00","bookable":true},{"start":"2026-09-03T16:30:00+02:00","end":"2026-09-03T17:00:00+02:00","bookable":false}]}}}}}}},"/sessions/{sessionId}/feedback":{"parameters":[{"name":"sessionId","in":"path","required":true,"schema":{"type":"string","example":"sess_9a44"}}],"post":{"tags":["Feedback"],"summary":"Record feedback after an evaluation","description":"The basis for reporting back to the agent's owning team.","operationId":"createFeedback","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["requester_id","adoption_likelihood"],"properties":{"requester_id":{"type":"string","example":"req_71ab"},"adoption_likelihood":{"type":"string","enum":["intent_to_adopt","still_evaluating","not_adopting"]},"cost_assessment":{"type":"string","enum":["fair","too_high","too_low"]},"comment":{"type":"string","maxLength":1000}}}}}},"responses":{"201":{"description":"Recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"apiKey","in":"header","name":"apikey","description":"Every call carries an API key in the `apikey` header. You generate the\nkey in the Nexora AI portal under \"My Apps\"; it's shown exactly once.\n\nEach key has the scopes it's allowed to use attached to it. If one is\nmissing, the API responds with `403` and `code: \"scope_missing\"`; the\nmissing scope is in `details[].field`.\n"}},"responses":{"NotAuthenticated":{"description":"Key is missing, revoked or invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Record not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ValidationError":{"description":"The request doesn't match the schema","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Rate limit reached","headers":{"Retry-After":{"schema":{"type":"integer","example":12}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Page":{"type":"object","description":"Cursor-based pagination.","properties":{"count":{"type":"integer","example":25},"total":{"type":"integer","example":138},"next_cursor":{"type":"string","nullable":true,"example":"eyJzIjoyNX0"}}},"ErrorDetail":{"type":"object","properties":{"field":{"type":"string","example":"start"},"reason":{"type":"string","example":"missing"}}},"Error":{"type":"object","description":"Uniform error format across all Nexora AI APIs.","required":["code","message"],"properties":{"code":{"type":"string","example":"validation_failed"},"message":{"type":"string","example":"The session start time is missing."},"details":{"type":"array","items":{"$ref":"#/components/schemas/ErrorDetail"}}}},"SessionStatus":{"type":"string","enum":["scheduled","confirmed","completed","cancelled"],"example":"confirmed"},"SessionType":{"type":"string","enum":["individual","group","virtual"],"example":"individual"},"SessionInput":{"type":"object","required":["agent_id","type","start"],"properties":{"agent_id":{"type":"string","example":"agt_8f2c1a"},"type":{"$ref":"#/components/schemas/SessionType"},"start":{"type":"string","format":"date-time","example":"2026-09-03T16:00:00+02:00"},"duration_minutes":{"type":"integer","minimum":10,"maximum":240,"default":30},"slots":{"type":"integer","minimum":1,"description":"Only evaluated when `type: group`.","example":12},"location_or_link":{"type":"string","maxLength":200,"example":"https://meet.nexora.example/eval-8f2c1a"},"note":{"type":"string","maxLength":500,"example":"Please come with concrete workflows you want the agent to try."}}},"Session":{"allOf":[{"$ref":"#/components/schemas/SessionInput"},{"type":"object","properties":{"id":{"type":"string","example":"sess_9a44"},"status":{"$ref":"#/components/schemas/SessionStatus"},"confirmations_count":{"type":"integer","example":8},"waitlist_count":{"type":"integer","example":2},"created_at":{"type":"string","format":"date-time","example":"2026-08-20T11:02:10Z"}}}]},"Confirmation":{"type":"object","properties":{"id":{"type":"string","example":"conf_1f7c"},"session_id":{"type":"string","example":"sess_9a44"},"requester_id":{"type":"string","example":"req_71ab"},"state":{"type":"string","enum":["confirmed","waitlisted","cancelled","attended","no_show"]},"attendees":{"type":"integer","example":1},"confirmed_at":{"type":"string","format":"date-time","example":"2026-08-21T09:14:00Z"}}},"TimeSlot":{"type":"object","properties":{"start":{"type":"string","format":"date-time","example":"2026-09-03T16:00:00+02:00"},"end":{"type":"string","format":"date-time","example":"2026-09-03T16:30:00+02:00"},"bookable":{"type":"boolean","example":true}}},"Feedback":{"type":"object","properties":{"id":{"type":"string","example":"fb_60d2"},"session_id":{"type":"string","example":"sess_9a44"},"requester_id":{"type":"string","example":"req_71ab"},"adoption_likelihood":{"type":"string","example":"still_evaluating"},"cost_assessment":{"type":"string","example":"too_high"},"comment":{"type":"string","example":"Works well for triage, but the per-request cost is above what we budgeted."},"created_at":{"type":"string","format":"date-time","example":"2026-09-03T17:12:00Z"}}}}}}
```