Sign Up

Lists API

Back to API Documentation

Lists API Documentation

Manage collections of symbols, create custom lists and monitor multiple assets easily

Authentication Required

Please sign in or create an account to use the API. The basic API is free to use for everyone.

Sign In

The Lists API allows you to manage collections of symbols. You can create lists and add requests using different query types: website URLs, company names, or symbol tickers. The system will automatically process these queries to find the corresponding symbols.

Authentication

You can authenticate your API requests in two ways:

1. Using HTTP Headers

Include your API token in the request header:

X-API-Key: your_api_token

2. Using Query Parameters

Alternatively, you can pass your API token as a query parameter:

https://api.example.com/v1/u/lists?api_token=your_api_token

Note: Using the header method is recommended for production environments as it's more secure than exposing your token in URLs.

Query Types

When creating lists or adding requests, you can use different types of queries:

  • Website URLs (e.g., "apple.com", "google.com")
  • Company names (e.g., "McDonalds", "Tesla Inc")
  • Symbol tickers (e.g., "AAPL", "GOOGL")
The system will automatically process these queries to find the corresponding symbols.

Request Processing

When you submit a request:

  • The request is initially created with a 'pending' status
  • The system processes the query to find the corresponding symbol
  • Once processed, the symbol is added to the list
  • You can check the status of requests using the Get List Requests endpoint

Rate Limits

API calls are limited to 100 requests per minute per API token. If you exceed this limit, you'll receive a 429 Too Many Requests response.

API Reference

Explore the Lists API endpoints to create and manage collections of symbols

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

GET

Get News Feed for List

Get the news feed for this list

Endpoint

https://api.markets.sh/api/v1/u/lists/[list_id]/news

Parameters

NameValueType
offset

Offset for pagination. Starts at 0.

query
limit

Limit the number of news items returned. Set to 10 by default.

query
q

Query string for filtering news items with full text search.

query
q_embedding

Query the news items with search parameter that will be used for embedding search. Please not that the sorting might not be choronological using this parameter.

query
from

Start date for filtering news items. Defaults to 2 months ago.

query
to

End date for filtering news items. Defaults to 1 day ago.

query

Code Example

Response

return the news feed for the specified list ID. The response will contain a list of news items related to the list.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

GET

Get Lists

Retrieve all lists owned by the authenticated user.

Endpoint

https://api.markets.sh/api/v1/u/lists

Code Example

Response

Returns an array of lists owned by the user.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

GET

Get List by ID

Retrieve details of a specific list.

Endpoint

https://api.markets.sh/api/v1/u/lists/123e4567-e89b-12d3-a456-426614174000

Code Example

Response

Returns details of the specified list.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

POST

Create List with URL and Company

Create a new list with website URL and company name queries.

Endpoint

https://api.markets.sh/api/v1/u/lists

Code Example

Response

Returns the newly created list with its ID and the status of the requests.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

POST

Create List with Symbol Tickers

Create a new list using symbol tickers.

Endpoint

https://api.markets.sh/api/v1/u/lists

Code Example

Response

Returns the newly created list with its ID and the status of the requests.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

PUT

Update List

Update an existing list details.

Endpoint

https://api.markets.sh/api/v1/u/lists/123e4567-e89b-12d3-a456-426614174000

Code Example

Response

Returns the updated list details.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

DELETE

Delete List

Delete a specific list and all its associated requests and symbols.

Endpoint

https://api.markets.sh/api/v1/u/lists/123e4567-e89b-12d3-a456-426614174000

Code Example

Response

Returns 204 No Content on successful deletion.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

GET

Get List Symbols

Retrieve all symbols that have been processed for a specific list.

Endpoint

https://api.markets.sh/api/v1/u/lists/123e4567-e89b-12d3-a456-426614174000/symbols

Code Example

Response

Returns an array of symbols in the list with their details and status.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

GET

Get List Requests

Retrieve all pending and processed requests for a specific list.

Endpoint

https://api.markets.sh/api/v1/u/lists/123e4567-e89b-12d3-a456-426614174000/requests

Code Example

Response

Returns an array of requests with their processing status and details.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

POST

Add Request to List

Add a new request to an existing list.

Endpoint

https://api.markets.sh/api/v1/u/lists/123e4567-e89b-12d3-a456-426614174000/requests

Code Example

Response

Returns the created request with its status.

Please sign in or create an account to use the API

The basic API is free to use for everyone. You can use it to build your own app. Please login to get your API token.

DELETE

Delete Request from List

Remove a request from a list.

Endpoint

https://api.markets.sh/api/v1/u/lists/123e4567-e89b-12d3-a456-426614174000/requests/123e4567-e89b-12d3-a456-426614174000

Code Example

Response

Returns 204 No Content on successful deletion.