> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.zignallabs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.zignallabs.com/_mcp/server. # Discover Stories V1 POST https://api.zignallabs.com/discover/v1/stories Content-Type: application/json Allows the retrieval of individual stories with meta-data for a specific time range and query defined using Zignal's Freeform Boolean language. Each response is limited to 200 stories at a time. A 'next' token will be provided in the response that can be used to retrieve the next page of stories for the timeframe. - The date range must be in the last 100 days. - `start_time` will default to 30 days ago. `end_time` will default to now. - By default time is in UTC 'Z'. It can be modified replacing 'Z' with time offsets that can go from '+12:00' to '-12:00': `YYYY-MM-DDTHH:MM:SS±HH:MM`. - Date values are optional. Default to the last 24 hours when not specified. - Pagination: For a given date (timestamp) range, the 'total' field indicates the number of stories that fit the request. Of those results, 0 to 200 will be returned in the response. If the total exceeds the 200 limit, a 'next' token will be returned allowing the user to get the next block of results. - `next` is the token to retrieve the next page (if total results for request > 200). - `sorted_by` allows results to be retrieved in the order they were created (default) or in the order they were persisted in the Zignal platform. Possible values: `persisted_at` and `created_at`. If `persisted_at` is provided, only the last 2 days can be queried. Reference: https://docs.zignallabs.com/api-reference/data-api-discover/discover/discover-stories-v-1 ## OpenAPI Specification ```yaml openapi: 3.1.0 info: title: zignal-data-api-discover version: 1.0.0 paths: /discover/v1/stories: post: operationId: discoverStoriesV1 summary: Discover Stories V1 description: > Allows the retrieval of individual stories with meta-data for a specific time range and query defined using Zignal's Freeform Boolean language. Each response is limited to 200 stories at a time. A 'next' token will be provided in the response that can be used to retrieve the next page of stories for the timeframe. - The date range must be in the last 100 days. - `start_time` will default to 30 days ago. `end_time` will default to now. - By default time is in UTC 'Z'. It can be modified replacing 'Z' with time offsets that can go from '+12:00' to '-12:00': `YYYY-MM-DDTHH:MM:SS±HH:MM`. - Date values are optional. Default to the last 24 hours when not specified. - Pagination: For a given date (timestamp) range, the 'total' field indicates the number of stories that fit the request. Of those results, 0 to 200 will be returned in the response. If the total exceeds the 200 limit, a 'next' token will be returned allowing the user to get the next block of results. - `next` is the token to retrieve the next page (if total results for request > 200). - `sorted_by` allows results to be retrieved in the order they were created (default) or in the order they were persisted in the Zignal platform. Possible values: `persisted_at` and `created_at`. If `persisted_at` is provided, only the last 2 days can be queried. tags: - discover responses: '200': description: Successful response content: application/json: schema: description: Any type requestBody: content: application/json: schema: type: object properties: ffb: type: string description: Freeform Boolean query string start_time: type: string default: 30 days ago description: >- Inclusive start date for time range. ISO 8601 Format: YYYY-MM-DDTHH:MM:SSZ end_time: type: string default: now description: >- Exclusive end date for time range. ISO 8601 Format: YYYY-MM-DDTHH:MM:SSZ next: type: string description: Pagination token for next set of stories required: - ffb servers: - url: https://api.zignallabs.com description: https://api.zignallabs.com ``` ## Examples **Request** ```json { "ffb": "source:(twitter OR news OR blogs) \"Super Bowl\"", "start_time": "2026-05-11T12:00:00Z", "end_time": "2026-05-16T16:00:00Z" } ``` **SDK Code** ```python Discover_discoverStoriesV1_example import requests url = "https://api.zignallabs.com/discover/v1/stories" payload = { "ffb": "source:(twitter OR news OR blogs) \"Super Bowl\"", "start_time": "2026-05-11T12:00:00Z", "end_time": "2026-05-16T16:00:00Z" } headers = {"Content-Type": "application/json"} response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Discover_discoverStoriesV1_example const url = 'https://api.zignallabs.com/discover/v1/stories'; const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"ffb":"source:(twitter OR news OR blogs) \"Super Bowl\"","start_time":"2026-05-11T12:00:00Z","end_time":"2026-05-16T16:00:00Z"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Discover_discoverStoriesV1_example package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.zignallabs.com/discover/v1/stories" payload := strings.NewReader("{\n \"ffb\": \"source:(twitter OR news OR blogs) \\\"Super Bowl\\\"\",\n \"start_time\": \"2026-05-11T12:00:00Z\",\n \"end_time\": \"2026-05-16T16:00:00Z\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Discover_discoverStoriesV1_example require 'uri' require 'net/http' url = URI("https://api.zignallabs.com/discover/v1/stories") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Content-Type"] = 'application/json' request.body = "{\n \"ffb\": \"source:(twitter OR news OR blogs) \\\"Super Bowl\\\"\",\n \"start_time\": \"2026-05-11T12:00:00Z\",\n \"end_time\": \"2026-05-16T16:00:00Z\"\n}" response = http.request(request) puts response.read_body ``` ```java Discover_discoverStoriesV1_example import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.zignallabs.com/discover/v1/stories") .header("Content-Type", "application/json") .body("{\n \"ffb\": \"source:(twitter OR news OR blogs) \\\"Super Bowl\\\"\",\n \"start_time\": \"2026-05-11T12:00:00Z\",\n \"end_time\": \"2026-05-16T16:00:00Z\"\n}") .asString(); ``` ```php Discover_discoverStoriesV1_example request('POST', 'https://api.zignallabs.com/discover/v1/stories', [ 'body' => '{ "ffb": "source:(twitter OR news OR blogs) \\"Super Bowl\\"", "start_time": "2026-05-11T12:00:00Z", "end_time": "2026-05-16T16:00:00Z" }', 'headers' => [ 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp Discover_discoverStoriesV1_example using RestSharp; var client = new RestClient("https://api.zignallabs.com/discover/v1/stories"); var request = new RestRequest(Method.POST); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"ffb\": \"source:(twitter OR news OR blogs) \\\"Super Bowl\\\"\",\n \"start_time\": \"2026-05-11T12:00:00Z\",\n \"end_time\": \"2026-05-16T16:00:00Z\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Discover_discoverStoriesV1_example import Foundation let headers = ["Content-Type": "application/json"] let parameters = [ "ffb": "source:(twitter OR news OR blogs) \"Super Bowl\"", "start_time": "2026-05-11T12:00:00Z", "end_time": "2026-05-16T16:00:00Z" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.zignallabs.com/discover/v1/stories")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```