Sign In (Soon)
Reference

API Reference

Complete REST API documentation for the Villip communications platform.

Work in Progress — The API is under development and not yet accepting requests. The specification below is a preview of the planned endpoints and will be updated as development progresses. An interactive reference (powered by Stoplight Elements) will be available at launch.

Base URL

https://api.villip.xyz/v1

Authentication

All API requests require two headers: X-Villip-Key-ID (your public key ID, prefixed vk_live_ or vk_test_) and X-Villip-Key-Secret (your private key secret). Generate API keys from the Tenant Portal.

X-Villip-Key-ID: vk_live_abc123def456
X-Villip-Key-Secret: sk_live_789ghi012jkl

Endpoints

MethodEndpointDescription
POST/v1/sms/messagesSend an SMS message
GET/v1/sms/messages/:idRetrieve message status
GET/v1/sms/messagesList sent messages
GET/v1/balanceCheck account balance

Error Codes

CodeMeaning
400Bad Request. Check request body and parameters.
401Unauthorised. Invalid or missing API key.
403Forbidden. Insufficient permissions.
404Not Found. Resource does not exist.
429Too Many Requests. Rate limit exceeded.
500Internal Server Error. Contact support.

Rate Limits

Default rate limit is 100 requests per second per API key. Higher limits are available on request. Rate limit headers (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset) are included in every response.