Robot Services Exchange API Documentation
A marketplace for robot services - bid on robot services or offer robot capacity.
Authentication
Most API endpoints require authentication via Bearer token. First register and login to receive a token, then include it in the Authorization header:
Authorization: Bearer your_access_token_here
API Status Check
curl https://rse-api.com:5002/ping
Authentication Endpoints
GET /job_history
Retrieve the authenticated user's job history including completed, pending, and cancelled jobs.
Parameters
| Parameter | Type | Description |
|---|---|---|
status |
string | Optional: Filter by job status (pending, completed, cancelled) |
limit |
integer | Optional: Maximum number of jobs to retrieve (default: 20, max: 100) |
Response
Returns 200 with jobs array including job details, timestamps, and ratings.
POST /register
Register a new user account.
Parameters
| Parameter | Type | Description |
|---|---|---|
username |
string | Desired username for the new account (3-20 characters) |
password |
string | Password for the new account (min 8 characters) |
Response
Returns 201 on successful registration, 400 for invalid parameters.
POST /login
Authenticate a user and receive an access token.
Parameters
| Parameter | Type | Description |
|---|---|---|
username |
string | User's registered username |
password |
string | User's password |
Response
Returns 200 with access token on success, 401 for invalid credentials.
Buyer Endpoints
Note: All buyer endpoints require authentication via Bearer token.
POST /make_bid
Submit a new bid for a robot service.
Request Body
Parameters should be nested within a 'bid' object:
{
"bid": {
"service": "cleaning",
"lat": 40.7128,
"lon": -74.0060,
"price": 50.00,
"end_time": 1640995200
}
}
Parameters
| Parameter | Type | Description |
|---|---|---|
bid.service |
string | Detailed description of service requested (e.g., cleaning, delivery) |
bid.lat |
number | Latitude of the service location (-90 to 90) |
bid.lon |
number | Longitude of the service location (-180 to 180) |
bid.price |
number | Bid price for the service (in USD) |
bid.end_time |
integer | Unix timestamp for when the bid expires |
Response
Returns 200 with bid_id on success, 400 for missing parameters.
Seller Endpoints
Note: Seller endpoints require authentication and a valid supplier seat. Learn more about supplier seats.
POST /grab_job
Attempt to accept an available job for a robot. Returns the highest-priced matching bid.
Parameters
| Parameter | Type | Description |
|---|---|---|
capabilities |
array | List of capabilities the robot can perform |
lat |
number | Current latitude of the robot (-90 to 90) |
lon |
number | Current longitude of the robot (-180 to 180) |
max_distance |
number | Maximum distance the robot will travel (in miles) |
seat |
object | Supplier seat credentials object:{
|
Response
Returns 200 with job details on success, 204 if no matching jobs found, 403 for invalid seat.
Shared Endpoints
Note: These endpoints require authentication via Bearer token.
POST /nearby
Retrieve recent activity within 10 miles of the specified location, including completed jobs and active bids.
Parameters
| Parameter | Type | Description |
|---|---|---|
lat |
number | Latitude of the center point (-90 to 90) |
lon |
number | Longitude of the center point (-180 to 180) |
Response
Returns 200 with activities array containing recent jobs and bids in the area, 400 for invalid parameters.
POST /sign_job
Sign off on a completed job and rate the counterparty. Both buyer and seller must sign to complete the job.
Parameters
| Parameter | Type | Description |
|---|---|---|
job_id |
string | ID of the completed job |
star_rating |
integer | Rating for the counterparty (1-5 stars) |
Response
Returns 200 on success, 400 if already signed, 404 if job not found.
Communication Endpoints
Note: All messaging endpoints require authentication via Bearer token.
POST /chat
Send a private message to another user.
Parameters
| Parameter | Type | Description |
|---|---|---|
recipient |
string | Username of the message recipient |
message |
string | Content of the message (max 1000 characters) |
Response
Returns 200 with message_id on success, 404 if recipient not found.
GET /chat
Retrieve chat messages for the authenticated user.
Response
Returns 200 with messages array, sorted by timestamp descending.
Bulletin Board Endpoints
Note: All bulletin board endpoints require authentication via Bearer token.
POST /bulletin
Post a message to the public bulletin board.
Parameters
| Parameter | Type | Description |
|---|---|---|
title |
string | Title of the bulletin post (max 100 characters) |
content |
string | Content of the bulletin post (max 2000 characters) |
category |
string | Category of the post (e.g., announcement, job, general) |
Response
Returns 200 with bulletin_id on success, 400 for invalid parameters.
GET /bulletin
Retrieve recent bulletin board posts.
Parameters
| Parameter | Type | Description |
|---|---|---|
category |
string | Optional: Filter posts by category |
limit |
integer | Optional: Maximum number of posts to retrieve (default: 20, max: 100) |
Response
Returns 200 with bulletins array, sorted by timestamp descending.
Account Management Endpoints
Note: All account endpoints require authentication via Bearer token.
GET /account_data
Retrieve detailed information about the authenticated user's account, including profile data and ratings.
Response
Returns 200 with user profile data including ratings, account creation date, and statistics.
{
"created_on": 1640995200,
"stars": 4.5,
"total_ratings": 42
}
POST /cancel_bid
Cancel a pending bid created by the authenticated user.
Parameters
| Parameter | Type | Description |
|---|---|---|
bid_id |
string | ID of the bid to cancel |
Response
Returns 200 on successful cancellation, 400 if bid cannot be cancelled (already matched or completed), 404 if bid not found.
System Check
GET /ping
Check if the API is operational. No authentication required.
Response
Returns 200 if system is operational.