API Reference

Complete reference for the Rowporter REST API v1.

Base URL

https://rowporter.com/api/v1

Authentication

All API requests require authentication using an API key. Include your key in the Authorization header:

Authorization: Bearer your_api_key

Keep your API key secure

Never expose your API key in client-side code. Use environment variables on your server.

Rate Limiting

API requests are rate limited to ensure fair usage. Limits are applied per API key.

Endpoint Type	Limit	Window
Read operations (GET)	100 requests	per minute
Write operations (POST/PATCH/DELETE)	30 requests	per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705312800

Endpoints

Method	Endpoint	Description
GET	/api/v1/templates	List all templates
POST	/api/v1/templates	Create a new template
GET	/api/v1/templates/:id	Get a specific template
PATCH	/api/v1/templates/:id	Update a template
DELETE	/api/v1/templates/:id	Delete a template
GET	/api/v1/imports	List all imports
GET	/api/v1/imports/:id	Get import details

Templates

GET/templates

List all templates for your organization.

Query Parameters

page	integer	Page number (default: 1)
limit	integer	Items per page (default: 20, max: 100)

Example Request

curl https://rowporter.com/api/v1/templates \
  -H "Authorization: Bearer sk_live_xxx"

Example Response

{
  "data": [
    {
      "id": "tpl_abc123",
      "name": "Contact Import",
      "description": "Import contact information",
      "columns": [...],
      "allowExtraColumns": false,
      "skipHeaderRows": 1,
      "importCount": 45,
      "createdAt": "2024-01-10T10:00:00Z",
      "updatedAt": "2024-01-15T14:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 5,
    "totalPages": 1
  }
}

POST/templates

Create a new import template.

Request Body

{
  "name": "Contact Import",           // required, string
  "description": "Import contacts",    // optional, string
  "columns": [                         // required, array
    {
      "key": "email",                  // required, unique identifier
      "name": "Email Address",         // required, display name
      "type": "email",                 // required: string|number|email|date|boolean|url|phone
      "required": true,                // optional, default: false
      "description": "Help text",      // optional
      "validations": [                 // optional, array of validation rules
        {
          "type": "regex",
          "value": "^[a-z]+@company\\.com$",
          "message": "Must be a company email"
        }
      ],
      "suggestedMappings": ["email", "e-mail", "email_address"]  // optional
    }
  ],
  "allowExtraColumns": false,          // optional, default: false
  "skipHeaderRows": 1,                 // optional, default: 1
  "allowPartialImport": false          // optional, default: false
}

Validation Rules

Type	Value	Description
minLength	number	Minimum string length
maxLength	number	Maximum string length
min	number	Minimum numeric value
max	number	Maximum numeric value
regex	string	Regular expression pattern
enum	array	Allowed values list
unique	boolean	No duplicate values in column

Example Request

curl -X POST https://rowporter.com/api/v1/templates \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Contact Import",
    "columns": [
      {"key": "email", "name": "Email", "type": "email", "required": true},
      {"key": "name", "name": "Full Name", "type": "string", "required": true},
      {"key": "age", "name": "Age", "type": "number", "validations": [{"type": "min", "value": 0}, {"type": "max", "value": 150}]}
    ]
  }'

GET/templates/:id

Get a specific template by ID.

Example Request

curl https://rowporter.com/api/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer sk_live_xxx"

PATCH/templates/:id

Update an existing template. Only include fields you want to change.

Example Request

curl -X PATCH https://rowporter.com/api/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Template Name"}'

DELETE/templates/:id

Delete a template. This will not delete associated imports.

Example Request

curl -X DELETE https://rowporter.com/api/v1/templates/tpl_abc123 \
  -H "Authorization: Bearer sk_live_xxx"

Imports

GET/imports

List all imports for your organization.

Query Parameters

page	integer	Page number
limit	integer	Items per page (max: 100)
templateId	string	Filter by template
status	string	Filter by status (COMPLETED, FAILED, PENDING)

Example Response

{
  "data": [
    {
      "id": "imp_xyz789",
      "templateId": "tpl_abc123",
      "templateName": "Contact Import",
      "fileName": "contacts.csv",
      "fileType": "csv",
      "fileSize": 15234,
      "totalRows": 150,
      "validRows": 145,
      "errorRows": 5,
      "status": "COMPLETED",
      "metadata": {"source": "dashboard"},
      "webhookStatus": "DELIVERED",
      "createdAt": "2024-01-15T10:30:00Z",
      "completedAt": "2024-01-15T10:30:45Z"
    }
  ],
  "pagination": {...}
}

GET/imports/:id

Get detailed information about a specific import.

Example Response

{
  "id": "imp_xyz789",
  "templateId": "tpl_abc123",
  "template": {
    "id": "tpl_abc123",
    "name": "Contact Import",
    "columns": [...]
  },
  "fileName": "contacts.csv",
  "fileType": "csv",
  "fileSize": 15234,
  "totalRows": 150,
  "validRows": 145,
  "errorRows": 5,
  "columnMapping": {
    "Email Address": "email",
    "Full Name": "name"
  },
  "status": "COMPLETED",
  "metadata": {"source": "dashboard"},
  "externalUserId": "user-123",
  "webhookStatus": "DELIVERED",
  "webhookAttempts": 1,
  "webhookDeliveredAt": "2024-01-15T10:30:50Z",
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:30:45Z"
}

Error Responses

All errors return a consistent JSON structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation error: name is required"
  }
}

Error Codes

HTTP Status	Code	Description
400	BAD_REQUEST	Invalid request parameters
400	VALIDATION_ERROR	Request body validation failed
401	UNAUTHORIZED	Invalid or missing API key
404	NOT_FOUND	Resource not found
429	RATE_LIMIT_EXCEEDED	Too many requests
500	INTERNAL_ERROR	Server error

← Getting Started SDK Reference