.png)
X API Integration Guide
Integrate X Posts, Users, media, search, streams, and selected account activity events with enterprise workflows through REST APIs and OAuth.
X API integration options at a glance
X API v2 provides REST endpoints for Posts, Users, Spaces, Lists, Direct Messages, search, relationships, and selected publishing operations. X also provides Filtered Stream and Sample Stream capabilities for applicable use cases, while Account Activity offers webhook-style notifications for selected account events rather than universal resource callbacks. Media uses dedicated upload and lookup endpoints, which may require OAuth 1.0a and legacy API behavior. Martini can consume these interfaces through workflows, store OAuth credentials in secrets, paginate or checkpoint retrievals, transform X JSON, apply business rules, and expose a controlled internal API façade.
| Integration point | Supported by X API? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Retrieve and search Posts, look up Users, access Spaces and Lists, manage permitted relationships, read selected Direct Messages, and create Posts for authorized users. | Martini can consume X REST endpoints, set query parameters and expansions, map JSON responses, and orchestrate downstream writes. |
| Streaming APIs | Yes | Filtered Stream supports near-real-time delivery of matching Posts; Sample Stream provides a sample of Posts where the account and plan permit access. | Martini can implement a streaming-compatible ingestion pattern, apply filtering and deduplication, and route normalized events into workflows or downstream APIs. |
| Webhooks / outbound callbacks | Limited | The Account Activity API provides webhook-style notifications for selected account events, subject to access tier, application configuration, and supported event types. | Martini can receive and process supported notifications, but workflows should not assume that every Post, User, Space, List, or Direct Message change generates a callback. |
| Media upload and lookup APIs | Limited | Upload images, videos, or GIFs and associate returned media identifiers with Posts. Authentication and endpoint behavior may differ from standard v2 calls. | Martini can orchestrate upload, capture the media ID, verify required processing, and then create the related Post. |
| Bulk / multi-ID lookup | Limited | Some endpoints support multiple Post or User IDs, pagination, and endpoint-specific lookup patterns, but a universal bulk export API was not confirmed. | Martini can batch endpoint-compatible requests while controlling response size, concurrency, pagination, and retries. |
| Authentication | Yes | X supports OAuth 2.0 authorization code with PKCE, OAuth 1.0a for selected legacy or media operations, and bearer tokens for eligible public read operations. | Martini can store credentials in environment-specific secrets, construct authorization headers, refresh supported tokens, and distinguish user context from application-only access. |
| File and attachment handling | Limited | Media is handled through X media endpoints and media identifiers rather than general-purpose file storage. | Martini can transform or receive binary content from an upstream system, call the X media endpoint, and pass the resulting identifier into Post creation. |
| Database access | No | X does not expose general-purpose SQL, JDBC, or direct database access; metrics and other data are obtained through API resources. | Martini can write retrieved and transformed X data to supported downstream databases, but it cannot query an X database directly. |
How X API exposes data and business events
X API REST APIs
X API v2 is primarily REST-based and exposes resource-specific endpoints for Posts, Users, Spaces, Lists, Direct Messages, search, relationships, and publishing. Responses can be shaped with fields, expansions, pagination, and filters, subject to permissions and access tier.
Martini implementation pattern
Martini implementation pattern: Martini stores the required bearer or user-context credentials in secrets, invokes the relevant X endpoint, validates the response, maps X JSON into a canonical model, and writes or forwards the result. A workflow persists pagination tokens or ID checkpoints and distinguishes authorization, rate-limit, validation, and transient server errors.
Implementation sequence
X Filtered and Sample Streams
Filtered Stream can deliver matching Posts in near real time when rules and access are configured. Sample Stream provides a sample rather than a complete change feed, so neither should be treated as a universal object-change stream.
Martini implementation pattern
Martini implementation pattern: a streaming-compatible ingestion design receives matching stream data, validates and normalizes each Post, uses the Post ID for duplicate protection, and routes events to downstream workflows. Reconnection, checkpointing, access restrictions, and backpressure must be designed for the deployment environment.
Implementation sequence
X Account Activity Webhooks
The Account Activity API provides webhook-style notifications for selected account events. Availability and event coverage depend on the API product, access tier, application configuration, and legacy endpoint status; it is not a universal callback mechanism.
Martini implementation pattern
Martini implementation pattern: Martini exposes or receives the configured callback endpoint, validates the notification, retrieves additional X data when needed, and invokes a workflow for mapping and downstream processing. REST polling or streaming should remain available for resources not covered by account activity notifications.
Implementation sequence
X Media Upload APIs
X media endpoints handle upload and lookup for media attached to Posts. Media operations may use historical v1.1 behavior and OAuth 1.0a, with supported media types, modes, and limits dependent on the account's current access.
Martini implementation pattern
Martini implementation pattern: a workflow receives approved content and media, calls the upload endpoint with the required user context, stores the returned media ID, and creates the Post only after upload requirements are satisfied. Failed uploads and failed Post creation are tracked separately for safe recovery.
Implementation sequence
Common X API integration patterns
Pattern 1: Sync X Posts to a support platform
When to use this pattern
Use this pattern when selected public Posts should become support tickets or cases. Filtered Stream or search REST endpoints can identify relevant content, while Post IDs, author details, conversation identifiers, and timestamps provide the basis for routing and deduplication.
Integration direction
Example Mapping
| X API Field | Canonical Field | Target Field |
|---|---|---|
| id | externalPostId | source_reference |
| text | messageText | description |
| author_id | xUserId | requester_reference |
| conversation_id | conversationReference | conversation_key |
Martini implementation pattern
Martini receives or retrieves matching Posts, requests required expansions, applies privacy and escalation rules, and creates or updates a support record. The workflow stores the X Post ID as an external key, retries transient target failures with bounded backoff, and routes permission or rate-limit failures for review.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- error handling
- retry and duplicate protection
Pattern 2: Publish approved content with media
When to use this pattern
Use this pattern when a CMS, marketing application, or internal approval process authorizes content for an X account. Media publication requires a separate upload step before Post creation when images, videos, or GIFs are included.
Integration direction
Example Mapping
| X API Field | Canonical Field | Target Field |
|---|---|---|
| approved_text | postText | text |
| asset_binary | mediaContent | upload payload |
| source_content_id | sourceContentId | integration key |
| media_id | xMediaId | media.attachments |
Martini implementation pattern
Martini validates approval state and content rules, uploads media using the required authentication context, captures the media ID, and creates the Post. It persists the source-to-Post mapping, prevents duplicate publication on retry, and separates media failures from Post-creation failures.
Martini capabilities used
- workflows
- API consumption
- secrets management
- data transformation
- business rules
- error handling
Pattern 3: Schedule X monitoring data for reporting
When to use this pattern
Use this pattern when an organization needs recurring keyword, hashtag, account, or time-range monitoring for reporting. Search results should be treated as endpoint-specific data rather than a guaranteed permanent event log.
Integration direction
Example Mapping
| X API Field | Canonical Field | Target Field |
|---|---|---|
| id | postId | post_id |
| created_at | publishedAt | published_at |
| public_metrics | engagementMetrics | metrics_json |
| entities.hashtags | hashtags | hashtag_values |
Martini implementation pattern
A scheduled Martini workflow queries X with configured boundaries, follows pagination, transforms fields and metrics, and writes an idempotent reporting dataset. It stores high-water marks, respects rate limits, handles changing search coverage, and resumes from the last successful checkpoint.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination handling
- mapping and transformation
- database or API writes
- monitoring
Pattern 4: Process near-real-time X activity
When to use this pattern
Use this pattern when matching Posts or selected account activity must trigger alerts or operational workflows quickly. Filtered Stream is appropriate for matching public Posts when available, while Account Activity notifications cover only selected account events.
Integration direction
Example Mapping
| X API Field | Canonical Field | Target Field |
|---|---|---|
| id | eventId | external_event_id |
| text | eventText | message |
| author_id | actorId | actor_reference |
| created_at | eventTime | occurred_at |
Martini implementation pattern
Martini receives the stream-compatible event or account notification, validates the source, enriches it with current X data when necessary, and applies routing rules before sending an alert or invoking an enterprise API. The workflow records event IDs, handles reconnects or duplicate notifications, and retries downstream delivery safely.
Martini capabilities used
- event-driven workflows
- API consumption
- data enrichment
- business rules
- duplicate protection
- error handling
Applications commonly integrated with X API
X API can be integrated with named enterprise applications when organizations need to monitor public Posts, publish approved content, notify teams, or synchronize selected social data. These are API-led architecture patterns rather than claims of packaged vendor-to-vendor integrations.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Salesforce | Associate approved public social interactions or campaign activity with Accounts, Contacts, Leads, or Cases. | X API → Martini → Salesforce | Use X search or streaming workflows, normalize Post and User data, apply privacy and matching rules, and upsert Salesforce objects with the X Post ID or User ID as an external reference. |
| Zendesk | Convert selected Posts or account activity into support tickets for service teams. | X API → Martini → Zendesk | Consume matching Posts, deduplicate by Post ID, map author and conversation details to ticket fields, and route or retry ticket creation through a controlled workflow. |
| ServiceNow | Create incidents, cases, or tasks from monitored social activity that requires internal follow-up. | X API → Martini → ServiceNow | Receive or retrieve matching Posts, validate the business rules for escalation, map the content to ServiceNow fields, and record the source Post ID for idempotent updates. |
| HubSpot | Publish approved campaign content and associate selected social activity with marketing workflows. | HubSpot → Martini → X API | Receive approved content from HubSpot, upload media when required, create the Post for an authorized X user, and persist the source-to-Post identifier mapping for recovery. |
| Microsoft Teams | Send internal alerts for monitored Posts, campaign events, or account activity. | X API → Martini → Microsoft Teams | Use a scheduled, streaming-compatible, or selected account-activity workflow to filter events, format concise notifications, and send them to the appropriate Teams destination. |
| Power BI | Analyze synchronized Post, User, campaign, and engagement data through a downstream data store. | X API → Martini → Power BI | Retrieve paginated X data, normalize JSON fields and metrics, write durable results to a database or reporting feed, and expose a consistent model for Power BI consumption. |
How to build a X API integration in Martini
Objective
Configure the X application context and keep credentials outside workflow payloads and logs.
Instructions in Martini
- Choose OAuth 2.0 user context, OAuth 1.0a, or bearer authentication based on the endpoint
- Store client credentials, tokens, and secrets in environment-specific configuration
- Define required scopes and distinguish user authorization from application-only access
Objective
Select the integration trigger that matches the required freshness and event coverage.
Instructions in Martini
- Use a schedule for search, lookup, and incremental synchronization
- Use Filtered Stream for supported near-real-time matching Posts
- Use Account Activity notifications only for supported account events
- Expose a Martini API when an internal system initiates the process
Objective
Consume the relevant X resource while controlling pagination, fields, expansions, and access limitations.
Instructions in Martini
- Call the required REST or media endpoint
- Request only the fields and expansions needed downstream
- Persist pagination tokens, since IDs, or other durable checkpoints
- Classify authorization, access-tier, rate-limit, and transient responses
Objective
Coordinate X calls, enrichment, validation, and target-system operations as a maintainable Martini workflow.
Instructions in Martini
- Sequence media upload before Post creation when attachments are present
- Use conditional routing for endpoint-specific responses
- Keep source identifiers and processing status with the workflow state
- Separate retryable failures from permission and validation failures
Objective
Convert X JSON and media results into a stable canonical model for downstream applications.
Instructions in Martini
- Map Post, User, Space, List, Direct Message, and Media fields explicitly
- Handle absent optional fields and requested expansions safely
- Normalize timestamps, identifiers, metrics, and conversation relationships
- Apply privacy, retention, and content-handling rules
Objective
Ensure that only permitted, relevant, and approved data is synchronized or published.
Instructions in Martini
- Filter Posts by configured rules, accounts, keywords, or business conditions
- Validate publishing approval and required user scopes
- Use X Post IDs, User IDs, and source identifiers for idempotency
- Avoid treating handles or public data as unrestricted customer master data
Common X API data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Posts | Retrieve, search, publish, monitor, and synchronize text, replies, quotes, reposts, metrics, attachments, and conversation relationships. | Salesforce, Zendesk, ServiceNow, Power BI, data warehouses | Martini requests required fields and expansions, uses Post IDs for deduplication, maps JSON to target models, and checkpoints pagination or stream progress. |
| Users | Read profile data, public metrics, verification details, identifiers, and selected relationship information. | Salesforce, HubSpot, customer-data stores, reporting platforms | Martini validates authorization and privacy rules, maps stable User IDs separately from handles, and handles optional or unavailable fields. |
| Spaces | Retrieve live audio conversation state, hosts, speakers, and participants where exposed. | Reporting platforms, notification systems, data stores | Martini retrieves permitted fields, normalizes participant and state data, and applies endpoint-specific pagination and access handling. |
| Lists | Manage or synchronize curated collections of X Users where permitted. | CRM platforms, internal monitoring tools, databases | Martini uses List and User identifiers as external keys and applies access, pagination, and duplicate protections. |
| Direct Messages | Access or send private messages and conversations where the endpoint, user authorization, and access tier permit it. | Service platforms, CRM systems, approved messaging workflows | Martini keeps user-context credentials isolated, applies strict privacy rules, maps conversation identifiers, and distinguishes permission failures from transient errors. |
| Media | Upload and look up images, videos, and GIFs associated with Posts. | Content platforms, campaign systems, X Posts | Martini uploads media first, captures the media identifier, waits for required processing, and then passes the identifier to Post creation. |
Authentication and security considerations
Authentication choices
X supports OAuth 2.0 authorization code with PKCE for applicable user-context operations, OAuth 1.0a for selected legacy or media functions, and bearer tokens for eligible public read operations. Required scopes and endpoint access vary by account and API tier.
Credential protection
Martini can store client credentials, access tokens, refresh tokens, and signing material in environment-specific secrets rather than workflow payloads or logs.
Access and privacy
- Separate application-only access from user-context access.
- Request only the scopes required by the workflow.
- Handle revoked tokens, missing scopes, and access-tier restrictions explicitly.
- Apply organizational privacy, retention, and X policy requirements to retrieved data.
Operational considerations for X API integrations
Limits and pagination
Rate limits can vary by user, application, endpoint, and access tier. Workflows should honor reset information, use bounded backoff, control concurrency, and persist pagination tokens or high-water marks.
Idempotency
Use Post IDs, User IDs, Media IDs, and source-content identifiers as durable external keys. Publishing workflows should persist the source-to-Post mapping before allowing retries to create another Post.
Schema and access changes
Keep endpoint versions, scopes, field selections, expansions, and access assumptions configurable. Treat missing optional fields, deleted Posts, changing search behavior, and permission failures as expected conditions.
Testing and monitoring
- Test user-context, application-only, media, and failure scenarios separately.
- Monitor rate-limit, authentication, access-tier, and downstream write failures.
- Checkpoint stream or scheduled processing so interrupted runs can resume safely.
- Test webhook-style notifications as selected account events, not as a universal change feed.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration beyond scripts
Martini provides a maintainable workflow layer for authentication, REST calls, streaming-compatible ingestion, media sequencing, pagination, transformation, business rules, and downstream writes.
Reusable integration behavior
Teams can expose a controlled Martini API façade, centralize mappings and validation, and reuse error-handling and credential-management patterns across X workflows.
Operational control
- Separate retryable failures from authorization and access-tier errors.
- Persist checkpoints and external identifiers for reliable recovery.
- Keep secrets and environment configuration separate from integration logic.
- Monitor workflow execution and troubleshoot failures without duplicating point-to-point code.
Frequently asked questions
X API can be integrated through its REST APIs for Posts, Users, Spaces, Lists, Direct Messages, search, and permitted publishing operations. Filtered Stream and Sample Stream support selected streaming use cases, while Account Activity provides limited webhook-style notifications for selected account events. Media uses dedicated upload and lookup endpoints, and authentication may use OAuth 2.0, OAuth 1.0a, or bearer tokens depending on the operation.
Yes. Martini can integrate with X API by consuming its REST and media endpoints, managing confirmed authentication methods through secrets, processing supported streams or account activity notifications, mapping X JSON, and orchestrating downstream workflows. No native Martini X connector is documented in the supplied sources.
No. A dedicated X API connector is not required. Martini can use X's confirmed REST APIs, streaming endpoints, media upload APIs, authentication methods, and limited webhook-style account activity capabilities through workflows and APIs.
Lonti does not charge an additional per-connector or per-vendor fee to integrate X API. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from X, cloud infrastructure, or other third-party systems based on subscription, usage, and deployment model.
Use X REST APIs for resource retrieval, search, lookup, and permitted publishing. Use Filtered Stream when near-real-time matching Posts is required and available. Use Account Activity only for supported account events, and use media endpoints as a separate upload step when publishing attachments. GraphQL and SOAP were not confirmed as public X integration interfaces.
No. Filtered Stream and Sample Stream support selected Post streaming scenarios, and Account Activity supports webhook-style notifications for selected account events. X does not provide a basis for claiming that every Post, User, Space, List, or Direct Message change produces an outbound callback.
Martini can use endpoint-specific pagination, since IDs, time windows, or stream processing state, together with durable checkpoints. X Post IDs, User IDs, Media IDs, and source-content identifiers can serve as external keys so downstream writes are idempotent and retries do not create duplicate results.
Martini can distinguish rate limits, authentication failures, missing scopes, invalid filters, unavailable resources, and transient server errors. Workflows can inspect response information, apply bounded backoff, reduce concurrency, persist progress, and resume from a checkpoint without repeating successful writes.
Related Martini documentation
Martini APIs
Workflows
Build a reliable X API integration with Martini
Use Martini to connect X API resources and selected event mechanisms with enterprise applications through secure, observable workflows and reusable API-led integration assets.