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
POST	/api/v1/templates/:id/duplicate	Duplicate 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
GET	/api/v1/organization/branding	Get branding/white-label settings
PUT	/api/v1/organization/branding	Update branding/white-label settings

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

bash

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

Example Response

json

{
  "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

json

{
  "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

bash

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

bash

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

bash

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

bash

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

POST/templates/:id/duplicate

Create a copy of an existing template. The duplicate will have "(Copy)" appended to its name and inherit all column definitions, validation rules, and settings from the original.

Example Request

bash

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

Example Response

json

{
  "id": "tpl_xyz789",
  "name": "Contact Import (Copy)",
  "description": "Import contacts from CSV",
  "columns": [...],
  "allowExtraColumns": false,
  "skipHeaderRows": 1,
  "allowPartialImport": false,
  "embedEnabled": true,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

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

json

{
  "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

json

{
  "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"
}

Branding / White-Label

GET/organization/branding

Get the current branding and white-label settings for your organization.

Example Request

bash

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

Example Response

json

{
  "primaryColor": "#3B82F6",
  "secondaryColor": "#1E40AF",
  "accentColor": "#10B981",
  "backgroundColor": "#FFFFFF",
  "textColor": "#111827",
  "borderColor": "#E5E7EB",
  "errorColor": "#EF4444",
  "successColor": "#22C55E",
  "logoUrl": "https://example.com/logo.png",
  "faviconUrl": null,
  "showPoweredBy": true,
  "fontFamily": "Inter, system-ui, sans-serif",
  "headingFontFamily": "Inter, system-ui, sans-serif",
  "fontSize": "medium",
  "borderRadius": "medium",
  "buttonStyle": "filled",
  "headerStyle": "default",
  "customCss": null,
  "customWelcomeText": null,
  "customSuccessText": null,
  "customErrorText": null,
  "locale": "en"
}

PUT/organization/branding

Update branding and white-label settings. Only include fields you want to change.

Request Body

Field	Type	Description
primaryColor	string	Hex color for primary elements
secondaryColor	string	Hex color for secondary elements
accentColor	string	Hex color for accent highlights
backgroundColor	string	Hex color for widget background
textColor	string	Hex color for text
borderColor	string	Hex color for borders
errorColor	string	Hex color for error states
successColor	string	Hex color for success states
logoUrl	string	URL to your logo image
showPoweredBy	boolean	Show/hide Powered by badge (paid plans only)
fontFamily	string	CSS font-family for body text
fontSize	string	"small" \| "medium" \| "large"
borderRadius	string	"none" \| "small" \| "medium" \| "large" \| "full"
buttonStyle	string	"filled" \| "outline" \| "ghost"
customCss	string	Custom CSS to inject
customWelcomeText	string	Custom welcome message
customSuccessText	string	Custom success message
locale	string	Language code (en, es, fr, de, pt, it, nl, ja, zh, ko)

Example Request

bash

curl -X PUT https://rowporter.com/api/v1/organization/branding \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#6366F1",
    "logoUrl": "https://example.com/new-logo.png",
    "showPoweredBy": false,
    "borderRadius": "large",
    "customWelcomeText": "Upload your file to import data"
  }'

Example Response

json

{
  "success": true,
  "message": "Branding settings updated successfully"
}

Plan Restrictions

Some branding features require a paid plan. Free plan users can only update primaryColor, secondaryColor, and logoUrl. Features like showPoweredBy: false and customCss require Starter plan or above.

Error Responses

All errors return a consistent JSON structure:

json

{
  "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