AY-ROBOTSAI Teleoperation
Sign Up

API 레퍼런스

AY-Robots REST API는 https://www.ay-robots.com/api 아래에 있으며 요청과 응답 모두 JSON을 사용합니다. 이 페이지는 인증 방식, 응답 규칙, 그리고 프로그래밍 방식으로 호출할 가능성이 높은 경로에 대한 전체 파라미터 문서를 포함한 모든 엔드포인트를 설명합니다.

마지막 업데이트 2026-08-09

인증

공개 섹션에 나열된 엔드포인트를 제외한 모든 엔드포인트는 인증이 필요합니다. API는 두 가지 형태의 자격 증명을 받아들이며, 둘 다 같은 방식으로 전달됩니다. 대시보드가 이미 보내는 세션 쿠키이거나, Bearer 토큰이 담긴 Authorization 헤더입니다.

방식작동 원리사용 목적
브라우저 세션로그인한 계정의 Supabase 세션 토큰을 쿠키 또는 Bearer 토큰으로 전송대시보드 자체와 인증된 브라우저 컨텍스트에서의 빠른 실험
API 키ayr_live_ 접두사가 붙은 키를 /dashboard/settings에서 생성해 Bearer 토큰으로 전송스크립트, 서버, CI, 브라우저 로그인에 의존해서는 안 되는 모든 것
MCPhttps://www.ay-robots.com/api/mcp의 호스팅 MCP 서버(Streamable HTTP)Model Context Protocol을 사용하는 LLM 에이전트와 도구
bash
curl https://www.ay-robots.com/api/sessions \
  -H 'Authorization: Bearer ayr_live_your_key_here'
API 키로 인증하기

API 키는 /dashboard/settings에서 생성하고 폐기합니다. 비밀번호처럼 다루십시오. 서버 측에만 보관하고, 기존 키를 폐기하기 전에 대체 키를 먼저 만들어 교체하십시오. 데스크톱 CLI를 사용한다면 다음 명령으로 플랫폼을 로컬 MCP 서버로도 노출할 수 있습니다: ay-robots mcp.

응답은 JSON입니다. 오류는 일관된 형태를 사용합니다. 사람이 읽을 수 있는 메시지를 담은 단일 error 필드가 있는 JSON 객체이며, 적절한 4xx 또는 5xx 상태 코드와 함께 전달됩니다. 성공 응답은 리소스를 직접 반환합니다. 일부 엔드포인트는 목록을 이름이 붙은 필드로 감싸며, 이는 아래 예시에서 해당될 때마다 표시합니다.

인증(Auth) 엔드포인트

계정과 프로필 관련 기본 기능입니다. 주로 대시보드 자체가 사용하지만, 유효한 자격 증명이 있다면 어디서든 동작합니다.

GET/api/auth/profileBearer 세션 토큰 또는 API 키

인증된 사용자의 프로필을 반환합니다.

POST/api/auth/profileBearer 세션 토큰 또는 API 키

표시 이름, 알림 설정 등 프로필 필드를 업데이트합니다.

POST/api/auth/syncBearer 세션 토큰

Supabase 인증 사용자를 플랫폼 사용자 레코드와 동기화합니다.

GET/api/auth/check-onboardingBearer 세션 토큰

인증된 사용자가 온보딩을 완료했는지 여부를 반환합니다.

POST/api/auth/avatarBearer 세션 토큰

인증된 사용자의 새 아바타 이미지를 업로드합니다.

클라이언트 엔드포인트

로봇 소유자가 관리하는 모든 것입니다. 등록된 로봇, 클라이언트 프로필, 데이터셋, 청구서, 대시보드 통계를 다룹니다.

GET/api/client/robotsBearer 세션 토큰 또는 API 키(클라이언트 역할)

인증된 클라이언트가 등록한 로봇을 최신순으로 최대 50개까지 나열합니다. 타임스탬프는 ISO 8601 형식이며, last_online과 last_heartbeat는 로봇이 한 번도 접속하지 않았다면 null입니다.

Request
curl https://www.ay-robots.com/api/client/robots \
  -H 'Authorization: Bearer ayr_live_your_key_here'
Response
[
  {
    "id": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11",
    "name": "Lab SO-100",
    "robot_type": "SO-100",
    "status": "AVAILABLE",
    "control_url": "wss://robots.example.com/so100/control",
    "stream_url": "https://robots.example.com/so100/stream",
    "hardware_id": "board:local:usb-1",
    "last_online": "2026-08-09T10:12:00.000Z",
    "last_heartbeat": "2026-08-09T10:12:00.000Z",
    "total_hours": 12.5,
    "tags": ["lab"],
    "notes": null,
    "created_at": "2026-07-01T09:00:00.000Z"
  }
]
POST/api/client/robotsBearer 세션 토큰 또는 API 키(클라이언트 역할)

새 로봇을 등록하고 그 id를 반환합니다. 모터 보드 하드웨어 id는 단 하나의 로봇에만 속할 수 있으며, 충돌하면 상태 코드 409로 거부됩니다.

GET/api/client/profileBearer 세션 토큰 또는 API 키(클라이언트 역할)

인증된 사용자의 클라이언트 프로필을 반환합니다.

PATCH/api/client/profileBearer 세션 토큰 또는 API 키(클라이언트 역할)

클라이언트 프로필 필드를 업데이트합니다.

GET/api/client/datasetsBearer 세션 토큰 또는 API 키(클라이언트 역할)

클라이언트의 클라우드 데이터셋을 에피소드 수와 크기와 함께 나열합니다.

GET/api/client/invoicesBearer 세션 토큰 또는 API 키(클라이언트 역할)

클라이언트의 월별 청구서를 나열합니다.

GET/api/client/statsBearer 세션 토큰 또는 API 키(클라이언트 역할)

클라이언트 대시보드를 위한 사용 통계를 반환합니다.

오퍼레이터 엔드포인트

오퍼레이터 측 기능입니다. 프로필과 가용성, 인증, 스케줄링, 수익 통계를 다룹니다.

GET/api/operator/profileBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

인증된 사용자의 오퍼레이터 프로필을 반환합니다.

POST/api/operator/profileBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

오퍼레이터 프로필을 생성하거나 업데이트합니다.

GET/api/operator/available-robotsBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

현재 사용 가능하며 오퍼레이터의 인증과 일치하는 로봇을 나열합니다.

GET/api/operator/certificationsBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

오퍼레이터의 인증 요청과 그 상태를 나열합니다.

POST/api/operator/certificationsBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

특정 로봇 유형에 대한 인증을 요청합니다.

GET/api/operator/scheduleBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

오퍼레이터의 주간 가용성 일정을 반환합니다.

POST/api/operator/scheduleBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

주간 가용성 일정을 업데이트합니다.

GET/api/operator/availabilityBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

오퍼레이터의 현재 가용성을 반환합니다.

GET/api/operator/statsBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

오퍼레이터 대시보드를 위한 수익 및 세션 통계를 반환합니다.

세션

세션은 플랫폼의 핵심 리소스입니다. 하나의 세션은 오퍼레이터와 로봇 사이에서 이루어지는 하나의 연속된 원격 조작 참여입니다. 세션 상태는 PENDING, ACTIVE, PAUSED, COMPLETED, CANCELLED 순으로 이동합니다.

GET/api/sessionsBearer 세션 토큰 또는 API 키

인증된 사용자의 세션을 나열합니다. 오퍼레이터는 자신이 조작한 세션을, 클라이언트는 자신의 로봇에서 발생한 세션을 봅니다. 두 뷰의 필드 구성은 약간 다릅니다. 클라이언트 뷰에는 episodes_collected와 data_collected_mb가 포함되고, 오퍼레이터 뷰에는 operator_earnings_cents가 포함됩니다.

NameInTypeDescription
statusquerystring선택 사항. 세션 상태로 필터링합니다. 예: ACTIVE 또는 COMPLETED. 생략하면 전체를 나열합니다.
limitquerynumber선택 사항. 페이지 크기, 기본값 50, 최대 100.
offsetquerynumber선택 사항. 페이지네이션 오프셋, 기본값 0.
Request
curl 'https://www.ay-robots.com/api/sessions?status=COMPLETED&limit=10' \
  -H 'Authorization: Bearer ayr_live_your_key_here'
Response
{
  "sessions": [
    {
      "id": "6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30",
      "status": "COMPLETED",
      "started_at": "2026-08-08T14:00:12.000Z",
      "ended_at": "2026-08-08T14:47:31.000Z",
      "duration_minutes": 47,
      "client_charge_cents": 1175,
      "episodes_collected": 23,
      "data_collected_mb": 210.4,
      "rating": 5,
      "created_at": "2026-08-08T13:59:58.000Z",
      "robot_id": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11",
      "robot_name": "Lab SO-100",
      "robot_type": "SO-100",
      "operator_name": "Jane D."
    }
  ]
}
POST/api/sessionsBearer 세션 토큰 또는 API 키(오퍼레이터 역할)

사용 가능한 로봇에서 원격 조작 세션을 시작합니다. 오퍼레이터 역할이 필요합니다. 클라이언트는 세션을 시작할 수 없습니다. 한 오퍼레이터는 한 번에 최대 하나의 ACTIVE 또는 PAUSED 세션만 보유할 수 있으며, 로봇의 상태는 현재 AVAILABLE이어야 합니다. 즉시 시작되면 로봇은 IN_SESSION으로 전환되고 클라이언트에게 알림이 전송됩니다.

NameInTypeDescription
robotIdbodystring필수. 조작할 로봇의 id. 로봇은 AVAILABLE 상태여야 합니다.
operatorIdbodystring선택 사항. 명시적인 오퍼레이터 id. 기본값은 인증된 오퍼레이터입니다.
scheduledForbodystring (ISO 8601)선택 사항. 즉시 시작하는 대신 세션을 미래 시점에 예약합니다.
Request
curl -X POST https://www.ay-robots.com/api/sessions \
  -H 'Authorization: Bearer ayr_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"robotId": "1f9f4c1e-7f2a-4b7e-9a45-0f4d2b6c8a11"}'
Response
{
  "sessionId": "6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30",
  "status": "ACTIVE"
}
GET/api/sessions/[id]Bearer 세션 토큰 또는 API 키

단일 세션과 그 세부 정보를 반환합니다.

PATCH/api/sessions/[id]Bearer 세션 토큰 또는 API 키

세션 생명주기를 업데이트합니다: 일시정지, 재개, 종료 및 관련 작업.

POST/api/sessions/[id]/extendBearer 세션 토큰 또는 API 키(클라이언트, 세션 소유자)

세션 연장을 요청합니다. 세션을 소유한 클라이언트만 호출할 수 있으며 세션은 ACTIVE 상태여야 합니다. 요청은 세션 이벤트로 기록되며 오퍼레이터에게 알림이 전송됩니다. 실제 연장은 오퍼레이터가 요청에 응답할 때 이루어집니다.

NameInTypeDescription
idpathstring세션 id.
additionalMinutesbodynumber요청하는 연장 시간(분).
Request
curl -X POST https://www.ay-robots.com/api/sessions/6b0d2c9a-53f1-4f6e-8f1a-2c9d4e7b5a30/extend \
  -H 'Authorization: Bearer ayr_live_your_key_here' \
  -H 'Content-Type: application/json' \
  -d '{"additionalMinutes": 30}'
Response
{
  "message": "Extension request sent to operator"
}
GET/api/sessions/[id]/messagesBearer 세션 토큰 또는 API 키

세션의 채팅 메시지를 나열합니다.

POST/api/sessions/[id]/messagesBearer 세션 토큰 또는 API 키

세션에서 채팅 메시지를 전송합니다.

POST/api/sessions/[id]/rateBearer 세션 토큰 또는 API 키(클라이언트)

완료된 세션을 1점에서 5점 척도로 평가하며, 선택적으로 코멘트를 남길 수 있습니다.

POST/api/sessions/exportBearer 세션 토큰 또는 API 키

세션 데이터를 내보냅니다.

결제

모든 자금 이동은 Stripe를 통해 처리됩니다. 클라이언트 청구는 저장된 결제 수단이 연결된 Stripe 고객을 사용하고, 오퍼레이터 정산금은 Stripe Connect를 사용합니다. 플랫폼 자체는 카드나 은행 데이터를 저장하지 않습니다.

POST/api/stripe/customerBearer 세션 토큰(클라이언트 역할)

클라이언트 청구에 사용되는 Stripe 고객을 생성하거나 반환합니다.

GET/api/stripe/connectBearer 세션 토큰(오퍼레이터 역할)

오퍼레이터의 Stripe Connect 계정 상태를 반환합니다.

POST/api/stripe/connectBearer 세션 토큰(오퍼레이터 역할)

오퍼레이터 정산금을 위한 Stripe Connect 온보딩을 시작합니다.

POST/api/stripe/setup-intentBearer 세션 토큰(클라이언트 역할)

결제 수단을 저장하기 위한 Stripe SetupIntent를 생성합니다.

POST/api/stripe/portalBearer 세션 토큰(클라이언트 역할)

결제 수단과 청구서를 관리하기 위한 Stripe billing portal 세션을 생성합니다.

GET/api/stripe/payoutBearer 세션 토큰(오퍼레이터 역할)

인증된 오퍼레이터의 정산금 정보를 반환합니다.

POST/api/stripe/payoutBearer 세션 토큰(오퍼레이터 역할)

누적된 수익의 정산금 지급을 요청합니다. 최소 정산 금액은 10.00 EUR입니다.

POST/api/stripe/webhookStripe 웹훅 서명

Stripe 웹훅 이벤트를 수신합니다. API 클라이언트가 아니라 Stripe가 호출합니다.

공개 엔드포인트

이 엔드포인트들은 인증이 필요 없습니다. 모니터링, 마케팅 페이지, 상태 확인 도구에서 안전하게 호출할 수 있습니다.

GET/api/health

API와 데이터베이스 연결 상태를 확인합니다. 둘 다 정상이면 200을 반환합니다. 데이터베이스 확인이 실패하면 같은 형태에 status와 db가 error로 설정되고 HTTP 상태 503과 함께 반환됩니다.

Request
curl https://www.ay-robots.com/api/health
Response
{
  "status": "ok",
  "db": "ok",
  "timestamp": "2026-08-09T10:12:00.000Z"
}
GET/api/robots/[id]

지원되는 로봇 모델의 공개 정보를 반환합니다.

GET/api/public/pricing

현재 공개 가격 플랜을 반환합니다.

POST/api/contact

문의 양식 메시지를 제출합니다. 메시지는 먼저 저장된 뒤 이메일로 전송되므로, 일시적인 메일 장애로 메시지가 유실되지 않습니다. 이 경우 응답은 stored를 true로, delivered를 false로 보고하며 전송은 운영 측에서 재시도됩니다.

NameInTypeDescription
namebodystring필수. 이름.
emailbodystring필수. 회신을 받을 유효한 이메일 주소.
categorybodystring필수. 다음 중 하나: General Inquiry, Bug Report, Feature Request, Sales & Pricing, Partnership, Career/Jobs, Technical Support, Billing & Payments, Press & Media, Other.
subjectbodystring필수. 짧은 제목.
messagebodystring필수. 메시지 본문.
Request
curl -X POST https://www.ay-robots.com/api/contact \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Jane Doe",
    "email": "jane@example.com",
    "category": "Technical Support",
    "subject": "SO-100 pairing question",
    "message": "My arm shows as offline after pairing."
  }'
Response
{
  "success": true,
  "message": "Message sent successfully",
  "id": "b1f2c3d4-0000-0000-0000-000000000000",
  "stored": true,
  "delivered": true
}
POST/api/robot-request

아직 플랫폼에 없는 로봇 유형에 대한 지원을 요청합니다.

GET/api/stats

공개 플랫폼 통계를 반환합니다.

관련 문서
보안

AY-Robots가 계정과 실시간 로봇 제어를 보호하는 방법입니다. Supabase 인증, 역할 모델, API 키, 세션 보호 장치, 감사 추적, 암호화를 설명합니다.

세션

AY-Robots 세션의 작동 방식을 설명합니다. PENDING에서 COMPLETED까지의 생명주기, 모든 활동 이벤트, 세션 채팅, 평점, 연장, 학습 데이터까지 다룹니다.

이전
지원 로봇
다음
결제