Requests & Responses

API request format and response handling.

Request Format

Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_API_KEY
Content-Type	For POST/PUT	application/json or multipart/form-data
Accept	Optional	application/json (default)

JSON Requests

Most endpoints accept JSON payloads:

curl -X POST https://api.blocksecops.com/api/v1/scans \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_id": "abc123",
    "preset": "standard"
  }'

File Uploads

Use multipart/form-data for file uploads:

curl -X POST https://api.blocksecops.com/api/v1/contracts/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

Multiple files:

curl -X POST https://api.blocksecops.com/api/v1/contracts/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "[email protected]"

---

Response Format

All responses are JSON.

Success Response

{
  "id": "scan_abc123",
  "status": "completed",
  "created_at": "2025-01-15T10:30:00Z",
  "data": { ... }
}

List Response

{
  "data": [...],
  "total": 150,
  "page": 1,
  "page_size": 20
}

Error Response

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Contract ID is required",
    "details": {
      "field": "contract_id",
      "reason": "missing"
    }
  }
}

---

HTTP Status Codes

Success Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
202	Accepted	Request accepted for processing
204	No Content	Success with no response body

Client Error Codes

Code	Meaning	Description
400	Bad Request	Invalid parameters or malformed request
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid key but insufficient permissions
404	Not Found	Resource doesn't exist
409	Conflict	Resource state conflict
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Meaning	Description
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Upstream service error
503	Service Unavailable	Temporary maintenance
504	Gateway Timeout	Request timeout

---

Error Codes

Common error codes returned in the error.code field:

Code	Description
INVALID_REQUEST	Malformed request body
MISSING_FIELD	Required field not provided
INVALID_FIELD	Field value is invalid
RESOURCE_NOT_FOUND	Requested resource doesn't exist
PERMISSION_DENIED	Insufficient permissions
RATE_LIMITED	Too many requests
QUOTA_EXCEEDED	Plan quota exceeded
SCAN_IN_PROGRESS	Cannot modify during active scan
DUPLICATE_RESOURCE	Resource already exists

---

Content Types

Request Content Types

Type	Use Case
application/json	JSON payloads
multipart/form-data	File uploads

Response Content Types

Type	Use Case
application/json	All API responses
application/pdf	Report exports
text/csv	CSV exports