SmartShare API v1 Documentation

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

Authentication

Most API requests must be authenticated using an API Key. However, some endpoints related to managing specific resources might use Session Authentication if accessed directly through the web application context (though API Keys are generally recommended for programmatic access).

API Key Authentication:

  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

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

    Required Fields:

    • instagram_username (string): The Instagram username associated with a connected account.
    • schedule (object): Defines when the automation should run.
      • type (string): Schedule type (e.g., "daily", "weekly", "monthly").
      • time (string): Time in HH:MM format (e.g., "09:00").
      • timezone (string): IANA timezone name (e.g., "Europe/London", "America/New_York").
      • Specific fields may vary based on type.
    • generalDescription (string): A brief description of the automation's purpose.
    • promptDetails (string): Detailed instructions for content generation (e.g., AI image prompt).
    • mandatoryCaptionOrHashtags (string): Text or hashtags that must be included in the generated post.
    • generateExtraHashtags (boolean): Whether to automatically generate additional relevant hashtags.
    • contentType (string): The type of content to generate (e.g., "ai_generated").

    Optional Fields:

    • negativePrompt (string): Elements to exclude during AI image generation.

    Example:

    {
   "instagram_username": "your_instagram_handle",
   "schedule": {
      "type": "daily",
      "time": "14:30",
      "timezone": "America/Los_Angeles"
   },
   "generalDescription": "Daily tech news summary post",
   "promptDetails": "Generate an image representing the latest AI advancements",
   "negativePrompt": "blurry, low quality",
   "mandatoryCaptionOrHashtags": "#AI #TechNews",
   "generateExtraHashtags": true,
   "contentType": "ai_generated"
}

  • Success Response: 201 Created - Returns the newly created automation object or a success message.

    {
   // 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: User is not logged in.
    • 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: User is not logged in.
    • 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.

Update Automation Status

Updates the active status of a specific automation.

  • Method: PATCH
  • Path: /automations/{id}/status
  • Path Parameters:
    • id (string, required): The UUID of the automation.
  • Request Body: application/json 
    {
   "active": true // or false
}
  • Success Response: 200 OK 
    {
   "success": true,
    "message": "Automation status updated to true" // or false
 }
  • Authentication: API Key
  • Error Responses:
    • 400 Bad Request: Missing or invalid automation ID, invalid JSON, or missing/invalid active status in the body.
    • 401 Unauthorized: Invalid or missing API Key.
    • 404 Not Found: Automation with the specified ID not found.
    • 500 Internal Server Error: Failed to update the automation status.

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

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