Base URL:
https://nexus-share.com/api
🔐 Authentication
All requests require a valid token in the Authorization header:
Authorization: Bearer <token>
✅ Recommended: Personal Access Tokens (PATs)
The simplest way to authenticate is with a Personal Access Token. PATs are valid for 1 year, individually revocable, and don't require token refresh.
Create a PAT from the Admin → API Tokens tab in Nexus Share, then use it directly:
The simplest way to authenticate is with a Personal Access Token. PATs are valid for 1 year, individually revocable, and don't require token refresh.
Create a PAT from the Admin → API Tokens tab in Nexus Share, then use it directly:
curl -H "Authorization: Bearer nxs_pat_your_token_here" \
https://nexus-share.com/api/messages
💡 PAT Advantages:
- Valid for 1 year (no hourly refresh needed)
- Individually revocable without affecting your session
- Create separate tokens per integration (IDE, CI/CD, scripts)
- No need to expose your password
Alternative: Cognito JWT Token
You can also use a short-lived Cognito JWT token (expires after 1 hour):
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:
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 |
| 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}"
📚 Full Documentation: For complete API documentation, see the Markdown version.