REST API Quick Reference

🔐 Authentication

All requests require a valid Cognito JWT token in the Authorization header:

Authorization: Bearer <cognito-id-token>

Getting a JWT Token

To authenticate and get a JWT token, use this curl command:

Method 1: Direct API Authentication

# Set your credentials (use single quotes to avoid shell expansion)
CLIENT_ID='iklprbakdar4i2bgcrfd9l94r'
NEXUS_USER='your-email@example.com'
NEXUS_PASSWORD='your-password'

# Authenticate with Cognito
curl -X POST https://cognito-idp.eu-central-1.amazonaws.com/ \
  -H "Content-Type: application/x-amz-json-1.1" \
  -H "X-Amz-Target: AWSCognitoIdentityProviderService.InitiateAuth" \
  -d "{
    \"AuthFlow\": \"USER_PASSWORD_AUTH\",
    \"ClientId\": \"${CLIENT_ID}\",
    \"AuthParameters\": {
      \"USERNAME\": \"${NEXUS_USER}\",
      \"PASSWORD\": \"${NEXUS_PASSWORD}\"
    }
  }" | jq -r '.AuthenticationResult.IdToken'

Note: Replace your-email@example.com and your-password with your actual Nexus Share credentials. Use single quotes to prevent shell interpretation of special characters.

Method 2: Using Your Application

Log into the Nexus Share web application at https://nexus-share.com
Open browser DevTools (F12)
Go to Application → Local Storage or Session Storage
Find the JWT token (usually stored as idToken)
Copy the token value

Method 3: Using Cognito Hosted UI

You can also authenticate using the Cognito Hosted UI in a browser:

https://.auth.eu-central-1.amazoncognito.com/login?client_id=iklprbakdar4i2bgcrfd9l94r&response_type=token&redirect_uri=https://nexus-share.com

Cognito Domain: .auth.eu-central-1.amazoncognito.com

After login, the token will be in the URL fragment:

https://nexus-share.com#id_token=eyJraWQiOiJ...

This method is useful for:

Testing authentication in a browser
Getting a token for manual API testing
Understanding the OAuth2 flow

⏱️ Token Expiration: JWT tokens expire after 1 hour. Implement token refresh logic for long-running applications.

📡 API Endpoints

POST /messages

Creates a new message/post (draft or scheduled)

Request Body

Parameter	Type	Required	Description
`content`	string	Required	Message text (1-10000 chars)
`platforms`	array	Required	Array of platform names (x, linkedin, bluesky)
`scheduledFor`	string	Optional	ISO 8601 timestamp for scheduling
`title`	string	Optional	Message title (max 500 chars)

GET /messages

Retrieves all messages with pagination and filtering

Query Parameters

Parameter	Type	Required	Description
`limit`	number	Optional	Number of results (1-100, default: 20)
`nextToken`	string	Optional	Pagination cursor
`status`	string	Optional	Comma-separated list (DRAFT, SCHEDULED, PUBLISHED, FAILED)
`platform`	string	Optional	Filter by platform (X, LINKEDIN, BLUESKY)

GET /messages/{messageId}

Retrieves a single message by ID

PATCH /messages/{messageId}

Updates a message's content, schedule time, or target platforms

DELETE /messages/{messageId}

Deletes (cancels) a scheduled message

POST /messages/{messageId}/publish

Publishes a message immediately to all target platforms

📦 Data Models

Message Object

The Message object represents a social media post in the system.

{
  "id": "POST|username|1736853600000",
  "status": "SCHEDULED",
  "scheduledFor": "2025-01-20T10:00:00Z",
  "content": "My post content",
  "targets": ["x", "linkedin", "bluesky"],
  "title": "Optional post title",
  "createdAt": "2025-01-14T12:00:00Z",
  "updatedAt": "2025-01-14T12:00:00Z",
  "lastAttemptAt": null,
  "publishedAt": null,
  "error": null,
  "externalIds": null
}

Fields

Field	Type	Description
`id`	string	Unique message identifier (composite key format)
`status`	string	Current status: DRAFT, SCHEDULED, DIRECT, PUBLISHED, FAILED
`scheduledFor`	string \| null	ISO 8601 timestamp for scheduled publish time
`content`	string	Message text content (1-10000 characters)
`targets`	string[]	Array of platform names (lowercase)
`title`	string \| null	Optional message title (max 500 characters)
`createdAt`	string	ISO 8601 timestamp of creation
`updatedAt`	string	ISO 8601 timestamp of last update
`lastAttemptAt`	string \| null	ISO 8601 timestamp of last publish attempt
`publishedAt`	string \| null	ISO 8601 timestamp of successful publish
`error`	string \| null	Error message if publishing failed
`externalIds`	object \| null	Platform-specific post IDs (e.g., {"x": "123456"})

Status Values

DRAFT - Message created but not scheduled
SCHEDULED - Message scheduled for future publishing
DIRECT - Message is being published immediately
PUBLISHED - Message successfully published to all platforms
FAILED - Publishing failed (see error field for details)

Platform Values

Valid platform names (case-insensitive in requests, lowercase in responses):

x - X (Twitter)
linkedin - LinkedIn
bluesky - Bluesky

External IDs and Platform URLs

After a message is successfully published, the externalIds field contains platform-specific post identifiers. You can construct direct URLs to view the posts on each platform:

{
  "externalIds": {
    "x": "2012087424487219563",
    "linkedin": "urn:li:share:7417853116836069377",
    "bluesky": "3mcjqcipyyk2d"
  }
}

URL Construction

Platform	External ID Format	URL Template	Example
X (Twitter)	Numeric ID	`https://x.com/i/web/status/{id}`	View Example
LinkedIn	URN format	`https://www.linkedin.com/feed/update/{urn}`	View Example
Bluesky	Post rkey	`https://bsky.app/profile/{did}/post/{rkey}`	View Example

Note: For Bluesky, you'll need the user's DID (Decentralized Identifier) to construct the full URL. The DID is associated with the user's account and can be retrieved from the user's profile information.

Message List Response

{
  "messages": [
    {
      "id": "POST|username|1736853600000",
      "status": "SCHEDULED",
      "content": "My post content",
      "targets": ["x", "linkedin"],
      "scheduledFor": "2025-01-20T10:00:00Z",
      "createdAt": "2025-01-14T12:00:00Z",
      "updatedAt": "2025-01-14T12:00:00Z"
    }
  ],
  "pagination": {
    "limit": 20,
    "nextToken": "eyJwayI6IlVTRVIjLCJzayI6IlBPU1QifQ==",
    "hasMore": true
  }
}

Fields

Field	Type	Description
`messages`	Message[]	Array of message objects
`pagination.limit`	number	Number of results returned
`pagination.nextToken`	string \| null	Cursor for next page (use in nextToken query param)
`pagination.hasMore`	boolean	Whether more results are available

Error Response

{
  "error": "Validation Error",
  "details": "Content must be between 1 and 10000 characters"
}

Fields

Field	Type	Description
`error`	string	Brief error message
`details`	string	Detailed error information

⚠️ Error Handling

All error responses follow this format:

{
  "error": "Brief error message",
  "details": "Detailed error information"
}

Common HTTP Status Codes

Code	Description
`200`	Successful GET, PATCH, or POST (publish)
`201`	Successful POST (create)
`204`	Successful DELETE
`401`	Missing or invalid authentication
`403`	Not authorized
`404`	Resource not found
`409`	Cannot perform operation
`422`	Validation errors
`429`	Rate limit exceeded

💡 Examples

Create and Publish Immediately

# Create a draft message
curl -X POST https://nexus-share.com/api/messages \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello from REST API!",
    "platforms": ["x", "linkedin"]
  }'

# Publish immediately
curl -X POST https://nexus-share.com/api/messages/POST%7Cuser%7C1736853600000/publish \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Idempotency-Key: $(uuidgen)"

Schedule for Later

curl -X POST https://nexus-share.com/api/messages \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Scheduled post",
    "platforms": ["x", "bluesky"],
    "scheduledFor": "2025-01-20T10:00:00Z"
  }'

List Scheduled Messages

curl -X GET "https://nexus-share.com/api/messages?status=SCHEDULED&limit=10" \
  -H "Authorization: Bearer ${TOKEN}"

🚀 REST API Quick Reference

🔐 Authentication

Getting a JWT Token

Method 1: Direct API Authentication

Method 2: Using Your Application

Method 3: Using Cognito Hosted UI

📡 API Endpoints

Request Body

Query Parameters

📦 Data Models

Message Object

Fields

Status Values

Platform Values

External IDs and Platform URLs

URL Construction

Message List Response

Fields

Error Response

Fields

⚠️ Error Handling

Common HTTP Status Codes

💡 Examples

Create and Publish Immediately

Schedule for Later

List Scheduled Messages