Skip to main content

Making Requests

This guide covers the essentials of making requests to the Semaswift API.

Base URL​

All API requests should be made to:

https://api.semaswift.com

For sandbox/testing:

https://sandbox.semaswift.com

Request Format​

Headers​

Every request should include:

Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json
Accept: application/json

Optional headers:

X-Request-ID: unique-request-id    # For request tracking
X-Idempotency-Key: unique-key      # For safe retries (POST/PUT/DELETE)

HTTP Methods​

MethodUsage
GETRetrieve resources
POSTCreate new resources
PUTReplace entire resource
PATCHPartial update
DELETERemove resources

Request Body​

For POST, PUT, and PATCH requests, send JSON in the request body:

curl -X POST https://api.semaswift.com/api/v1/users \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "name": "New User",
    "role": "agent"
  }'

Response Format​

All responses are JSON:

{
  "id": "usr_123456",
  "email": "newuser@example.com",
  "name": "New User",
  "role": "agent",
  "created_at": "2024-01-15T10:30:00Z"
}

Success Responses​

StatusDescription
200 OKRequest succeeded
201 CreatedResource created
204 No ContentSuccess with no body (e.g., DELETE)

Error Responses​

{
  "code": 400,
  "message": "Validation failed",
  "details": [
    {
      "field": "email",
      "message": "Invalid email format"
    }
  ]
}

Pagination​

List endpoints return paginated results:

GET /api/v1/users?page_size=20&page_token=abc123

Response:

{
  "users": [...],
  "next_page_token": "def456",
  "total_count": 150
}

Pagination Parameters​

ParameterTypeDefaultDescription
page_sizeinteger20Items per page (max 100)
page_tokenstring-Token for next page

Filtering​

Many list endpoints support filtering:

GET /api/v1/tickets?status=open&priority=high&created_after=2024-01-01

Sorting​

Use the sort parameter:

GET /api/v1/users?sort=created_at:desc
GET /api/v1/tickets?sort=priority:asc,created_at:desc

Idempotency​

For safe retries on create/update operations, include an idempotency key:

curl -X POST https://api.semaswift.com/api/v1/payments \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-Idempotency-Key: unique-payment-id-12345" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD"
  }'

The same request with the same idempotency key will return the same response without creating duplicate resources.

Compression​

Enable response compression with:

Accept-Encoding: gzip

Timeouts​

We recommend setting these timeouts:

  • Connection timeout: 10 seconds
  • Read timeout: 30 seconds
  • For file uploads: 5 minutes

Example: Complete Request Flow​

# 1. Authenticate
TOKEN=$(curl -s -X POST https://api.semaswift.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"pass"}' | jq -r '.access_token')

# 2. Create a ticket
curl -X POST https://api.semaswift.com/api/v1/tickets \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: ticket-$(date +%s)" \
  -d '{
    "subject": "Help needed",
    "description": "I need assistance with my account",
    "priority": "medium"
  }'

# 3. List tickets with filters
curl "https://api.semaswift.com/api/v1/tickets?status=open&page_size=10" \
  -H "Authorization: Bearer $TOKEN"

Next Steps​