Skip to main content

​
GET /api/v1/surgeries//trajectory

Retrieve the complete trajectory data for a specific surgery session, including all recorded movements, timestamps, and any existing AI analysis.

​
Authentication

Requires JWT authentication with ROLE_SURGEON or ROLE_AI. Surgeons can only access their own surgeries, while AI systems can access all trajectories.

​
Path Parameters

​
id
UUID
required
Unique identifier of the surgery sessionExample: 550e8400-e29b-41d4-a716-446655440000

​
Authorization Rules

  • Surgeons (ROLE_SURGEON): Can only retrieve their own surgery trajectories
  • AI Systems (ROLE_AI): Can retrieve any surgery trajectory

​
Response

​
surgeryId
UUID
Unique identifier of the surgery session
​
startTime
LocalDateTime
Timestamp when the surgery started (ISO 8601 format)
​
endTime
LocalDateTime
Timestamp when the surgery finished (ISO 8601 format)
​
movements
Movement[]
Array of recorded movements during the surgeryEach movement contains:
  • coordinates: double[] - 3D coordinates [x, y, z]
  • event: SurgeryEvent - Event type (NONE, TUMOR_TOUCH, HEMORRHAGE, START, FINISH)
  • timestamp: long - Unix timestamp in milliseconds
​
score
Double
AI-generated performance score (0-100)null if analysis hasn’t been completed yet
​
feedback
String
AI-generated textual feedback and recommendationsnull if analysis hasn’t been completed yet

​
Code Examples

curl -X GET http://localhost:8080/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000/trajectory \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Response Examples

200 OK - With AI Analysis
{
  "surgeryId": "550e8400-e29b-41d4-a716-446655440000",
  "startTime": "2024-03-05T10:30:00",
  "endTime": "2024-03-05T10:45:30",
  "movements": [
    {
      "coordinates": [10.5, 20.3, 15.7],
      "event": "START",
      "timestamp": 1709636400000
    },
    {
      "coordinates": [10.8, 20.5, 15.9],
      "event": "NONE",
      "timestamp": 1709636401000
    },
    {
      "coordinates": [11.2, 21.0, 16.2],
      "event": "TUMOR_TOUCH",
      "timestamp": 1709636402500
    },
    {
      "coordinates": [11.5, 21.3, 16.5],
      "event": "FINISH",
      "timestamp": 1709637330000
    }
  ],
  "score": 87.5,
  "feedback": "Excellent precision during tumor removal. Movement trajectory was smooth with minimal tremor. Consider reducing speed during critical approach phases."
}
200 OK - Without AI Analysis
{
  "surgeryId": "650e8400-e29b-41d4-a716-446655440001",
  "startTime": "2024-03-05T14:15:00",
  "endTime": "2024-03-05T14:28:45",
  "movements": [
    {
      "coordinates": [5.2, 8.7, 12.3],
      "event": "START",
      "timestamp": 1709650500000
    },
    {
      "coordinates": [5.5, 9.0, 12.6],
      "event": "FINISH",
      "timestamp": 1709651325000
    }
  ],
  "score": null,
  "feedback": null
}
403 Forbidden
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 403,
  "error": "Forbidden",
  "message": "Access denied: You can only access your own surgeries",
  "path": "/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000/trajectory"
}
404 Not Found
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 404,
  "error": "Not Found",
  "message": "Surgery not found with ID: 550e8400-e29b-41d4-a716-446655440000",
  "path": "/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000/trajectory"
}

​
Surgery Event Types

The event field in each movement can have the following values:
EventDescription
STARTBeginning of the surgery session
NONENormal movement without special event
TUMOR_TOUCHSurgical instrument made contact with tumor
HEMORRHAGEHemorrhage event detected
FINISHEnd of the surgery session

​
POST /api/v1/surgeries//analysis

Submit AI-generated analysis results for a completed surgery. This endpoint is exclusively for AI systems to provide automated scoring and feedback.

​
Authentication

This endpoint requires ROLE_AI authentication. Surgeon accounts will receive 403 Forbidden errors.

​
Path Parameters

​
id
UUID
required
Unique identifier of the surgery session to analyzeExample: 550e8400-e29b-41d4-a716-446655440000

​
Request Body

​
score
double
required
Performance score for the surgery
  • Minimum: 0
  • Maximum: 100
  • Represents overall surgical performance quality
​
feedback
string
required
Detailed textual feedback and recommendations
  • Cannot be blank
  • Should include:
    • Performance highlights
    • Areas for improvement
    • Specific technique recommendations
    • Safety observations

​
Response

Returns 204 No Content on success with an empty response body.

​
Code Examples

curl -X POST http://localhost:8080/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000/analysis \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "score": 87.5,
    "feedback": "Excellent precision during tumor removal. Movement trajectory was smooth with minimal tremor. Consider reducing speed during critical approach phases."
  }'

​
Response Examples

204 No Content
(Empty response body)
400 Bad Request - Validation Error
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "El score no puede ser mayor a 100",
  "path": "/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000/analysis"
}
403 Forbidden - Surgeon Account
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 403,
  "error": "Forbidden",
  "message": "Access denied: Only AI systems can submit analysis",
  "path": "/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000/analysis"
}
404 Not Found
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 404,
  "error": "Not Found",
  "message": "Surgery not found with ID: 550e8400-e29b-41d4-a716-446655440000",
  "path": "/api/v1/surgeries/550e8400-e29b-41d4-a716-446655440000/analysis"
}

​
Workflow Example

Typical AI analysis workflow:
1

Surgery Completion

Surgeon completes a simulation, triggering a FINISH event via WebSocket
2

AI Notification

AI system receives NEW_SURGERY notification on /ws/ai channel with surgery ID
3

Fetch Trajectory

AI calls GET /surgeries/{id}/trajectory to retrieve movement data
4

Analyze Data

AI processes trajectory, calculates metrics, and generates feedback
5

Submit Analysis

AI calls POST /surgeries/{id}/analysis with score and feedback
6

Surgeon Access

Surgeon can now view AI feedback by fetching the trajectory again

​
Next Steps

WebSocket Overview

Learn about real-time telemetry streaming

AI Channel

Receive surgery completion notifications

Build docs developers (and LLMs) love

Get started for freeTalk to us