SmartShare API v1 Documentation

Welcome to the SmartShare API v1! This API allows you to manage your content automations programmatically.

Authentication

All API requests must be authenticated using an API Key.

  1. Generate your API Key: Go to your Account Settings page and generate a new API key.
  2. Include the Key in Requests: Send the API key in the Authorization header as a Bearer token.
Authorization: Bearer YOUR_API_KEY

Replace YOUR_API_KEY with the key you generated.

Base URL

All API endpoints are relative to the following base URL:

https://smartshare.social/api/v1

Rate Limiting

(Information about rate limits, if any, should be added here.)

Error Handling

Standard HTTP status codes are used to indicate the success or failure of an API request.

  • 2xx codes indicate success.
  • 4xx codes indicate a client error (e.g., missing parameters, invalid API key, resource not found).
  • 5xx codes indicate a server error.

Error responses will include a JSON body with error and message fields, and potentially a details field for validation errors.

{
   "error": "Error Type",
   "message": "A descriptive error message."
}

Endpoints

Automations

List Automations

Retrieves a list of all automations belonging to the authenticated user.

  • Method: GET

  • Path: /automations

  • Success Response: 200 OK

    {
   "automations": [
      {
         "id": "uuid-goes-here",
         "user_id": "user-uuid",
         "schedule": {
            /* Schedule object */
         },
         "general_description": "My daily cat post automation",
         "prompt_details": "Generate a cute cat picture",
         "content_type": "ai_generated",
         "ai_model": "default",
         "active": true,
         "status": "idle",
         "last_run_at": null,
         "next_scheduled_at": "2024-07-15T10:00:00Z",
         "created_at": "2024-06-10T12:00:00Z",
         "updated_at": "2024-06-10T12:00:00Z"
      }
      // ... more automations
   ]
}

  • Error Responses:

    • 401 Unauthorized: Invalid or missing API Key.
    • 500 Internal Server Error: Failed to retrieve automations.

Create Automation

Creates a new automation for the authenticated user.

  • Method: POST

  • Path: /automations

  • Request Body: application/json - Must match the AutomationFormValues structure (defined in app/automation/schemas.ts, excluding potentially instagramConnected and instagramUsername for API usage - needs clarification).

    {
   "schedule": {
      "type": "daily",
      "time": "09:00",
      "timezone": "Europe/London"
   },
   "contentType": "ai_generated",
   "generalDescription": "My new API automation",
   "promptDetails": "Generate a picture about coding",
   "aiModel": "dall-e-3"
}

  • Success Response: 201 Created - Returns the newly created automation object.

    {
   // Full automation object as created
   "id": "new-uuid-goes-here"
   // ... other fields
}

  • Error Responses:

    • 400 Bad Request: Invalid JSON or request body fails validation.
    • 401 Unauthorized: Invalid or missing API Key.
    • 403 Forbidden: User is not allowed to create more automations (e.g., free tier limit reached).
    • 500 Internal Server Error: Failed to create the automation.

Get Automation Details

Retrieves the details of a specific automation by its ID.

  • Method: GET
  • Path: /automations/{id}
  • Path Parameters:
    • id (string, required): The UUID of the automation.
  • Success Response: 200 OK - Returns the automation object. 
    {
   // Full automation object
   "id": "requested-uuid"
   // ... other fields
}
  • Error Responses:
    • 400 Bad Request: Missing or invalid automation ID format.
    • 401 Unauthorized: Invalid or missing API Key.
    • 404 Not Found: Automation with the specified ID not found or not accessible by the user.
    • 500 Internal Server Error: Failed to retrieve automation details.

Delete Automation

Deletes a specific automation by its ID.

  • Method: DELETE
  • Path: /automations/{id}
  • Path Parameters:
    • id (string, required): The UUID of the automation.
  • Success Response: 204 No Content
  • Error Responses:
    • 400 Bad Request: Missing or invalid automation ID format.
    • 401 Unauthorized: Invalid or missing API Key.
    • 404 Not Found: Automation with the specified ID not found or not accessible by the user.
    • 500 Internal Server Error: Failed to delete the automation.

Start Automation

Activates a specific automation (sets active to true).

  • Method: POST
  • Path: /automations/{id}/start
  • Path Parameters:
    • id (string, required): The UUID of the automation.
  • Success Response: 200 OK 
    {
   "success": true,
   "message": "Automation activated."
}
  • Error Responses:
    • 400 Bad Request: Missing or invalid automation ID format.
    • 401 Unauthorized: Invalid or missing API Key.
    • 404 Not Found: Automation with the specified ID not found or cannot be started.
    • 500 Internal Server Error: Failed to start the automation.

Stop Automation

Deactivates a specific automation (sets active to false).

  • Method: POST
  • Path: /automations/{id}/stop
  • Path Parameters:
    • id (string, required): The UUID of the automation.
  • Success Response: 200 OK 
    {
   "success": true,
   "message": "Automation deactivated."
}
  • Error Responses:
    • 400 Bad Request: Missing or invalid automation ID format.
    • 401 Unauthorized: Invalid or missing API Key.
    • 404 Not Found: Automation with the specified ID not found or cannot be stopped.
    • 500 Internal Server Error: Failed to stop the automation.

Webhooks

Webhooks allow your application to receive real-time notifications about specific events happening within SmartShare.

Configuration

You can configure webhook endpoints in your Account Settings page. SmartShare will send an HTTP POST request to your configured URL(s) when a subscribed event occurs.

Payload Structure

All webhook events send an HTTP POST request with a JSON payload following this basic structure:

{
  "event_type": "event.name.occurred",
  "timestamp": "2025-04-11T21:55:00.123Z", // ISO 8601 timestamp
  "data": {
    // Event-specific data goes here
  }
}
  • event_type (string): The type of event that occurred.
  • timestamp (string): The time the event occurred, in ISO 8601 format.
  • data (object): An object containing details specific to the event.

Available Events

Currently, the following events trigger webhooks:

instagram.post.published

Triggered when an Instagram post, scheduled via SmartShare, is successfully published to Instagram.

Example Payload:

{
  "event_type": "instagram.post.published",
  "timestamp": "2025-04-11T22:01:15.456Z",
  "data": {
    "postId": "uuid-of-the-smartshare-post-record"
    // "instagramPostId": "ig-media-id-if-available" // Note: Currently not included, may be added later
  }
}

automation.instagram.post.created

Triggered when an automation successfully runs and creates a new Instagram post record within SmartShare (status set to 'ready' for publishing).

Example Payload:

{
  "event_type": "automation.instagram.post.created",
  "timestamp": "2025-04-11T22:05:30.789Z",
  "data": {
    "automationId": "uuid-of-the-automation-that-ran",
    "createdPostId": "uuid-of-the-newly-created-post-record"
  }
}