{
  "info": {
    "name": "Nukoud Content API",
    "_postman_id": "b7e1c4a0-0000-4a00-9000-nukoudcontent1",
    "description": "Nukoud's GCC ETF news, analysis and fund coverage.\n\n**Setup**\n1. Open the collection's *Variables* tab and paste your key into `apiKey`.\n2. `baseUrl` is already set to production.\n3. Send **Reference \u2192 Who this key is** first \u2014 it echoes your key's name, scopes and rate limit, and is the quickest way to confirm the key works.\n\n**Authentication** is one header, `X-API-Key`, set at the collection level. Every request inherits it; you do not need to add it anywhere.\n\n**Conventions**\n- Every timestamp is ISO-8601 UTC.\n- Every list endpoint returns `{ items, meta }` with the same `meta`: page, page_size, total_items, total_pages, has_next.\n- Funds are identified by ticker AND ISO-2 listing country. A cross-listed strategy appears once per listing and the two are never merged.\n- Fields are added, never removed, without a version change. Ignore fields you do not recognise.\n\nFull reference: https://www.nukoud.com/developers",
    "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json"
  },
  "auth": {
    "type": "apikey",
    "apikey": [
      {
        "key": "key",
        "value": "X-API-Key",
        "type": "string"
      },
      {
        "key": "value",
        "value": "{{apiKey}}",
        "type": "string"
      },
      {
        "key": "in",
        "value": "header",
        "type": "string"
      }
    ]
  },
  "event": [
    {
      "listen": "test",
      "script": {
        "type": "text/javascript",
        "exec": [
          "// Runs after every request in this collection.",
          "pm.test('status is 2xx', () => pm.response.to.be.success);",
          "pm.test('body is JSON', () => pm.response.to.be.json);",
          "",
          "// Surface the two failures a new integration actually hits.",
          "if (pm.response.code === 401) {",
          "    console.warn('401 \u2014 set the apiKey collection variable.');",
          "} else if (pm.response.code === 429) {",
          "    console.warn('429 \u2014 over the per-minute limit. Retry-After: ' +",
          "        pm.response.headers.get('Retry-After'));",
          "}"
        ]
      }
    }
  ],
  "variable": [
    {
      "key": "baseUrl",
      "value": "https://www.nukoud.com/api/v1",
      "description": "Production. Nukoud may issue a test base URL during integration."
    },
    {
      "key": "apiKey",
      "value": "",
      "description": "Your key, e.g. nk_live_\u2026 \u2014 paste it here. Treat it as a password."
    },
    {
      "key": "articleSlug",
      "value": "gold-etfs-explained-8-different-ways-to-invest-in-gold",
      "description": "A real article, so the detail and batch requests work the moment you import. 'Latest articles' overwrites it with the newest slug when you run it."
    },
    {
      "key": "ticker",
      "value": "CHADX15",
      "description": "Filled automatically by 'Which funds have articles'."
    }
  ],
  "item": [
    {
      "name": "Articles",
      "description": "List endpoints return headlines, images and metadata \u2014 everything to render a card, and no body. Fetch the body from the detail or batch request when a reader opens the piece.",
      "item": [
        {
          "name": "Latest articles",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/articles?page_size=10",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "articles"
              ],
              "query": [
                {
                  "key": "page_size",
                  "value": "10",
                  "description": "1\u2013100, default 20"
                },
                {
                  "key": "page",
                  "value": "1",
                  "description": "default 1",
                  "disabled": true
                },
                {
                  "key": "section",
                  "value": "analysis",
                  "description": "news, analysis, education, research, opinion, tools",
                  "disabled": true
                },
                {
                  "key": "tag",
                  "value": "commodities-gold",
                  "description": "tag slug \u2014 see Reference \u2192 Editorial tags",
                  "disabled": true
                },
                {
                  "key": "ticker",
                  "value": "CHADX15",
                  "description": "only articles naming this fund",
                  "disabled": true
                },
                {
                  "key": "since",
                  "value": "2026-09-01T00:00:00Z",
                  "description": "ISO-8601; only articles published after this",
                  "disabled": true
                },
                {
                  "key": "sort",
                  "value": "newest",
                  "description": "newest | oldest | title",
                  "disabled": true
                }
              ]
            },
            "description": "Newest first. Filter by section, tag, ticker or publication date.\n\n**Polling:** store the newest `published_at` you have seen and pass it back as `since`. You then receive only what is new, so a five-minute poll costs one small request."
          },
          "response": [],
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "// Hand the first slug to the detail request, so it works without",
                  "// copying anything by hand.",
                  "const body = pm.response.json();",
                  "if (body.items && body.items.length) {",
                  "    pm.collectionVariables.set('articleSlug', body.items[0].slug);",
                  "}",
                  "pm.test('items carry a title, url and image', () => {",
                  "    const a = body.items[0];",
                  "    pm.expect(a).to.have.property('title');",
                  "    pm.expect(a).to.have.property('url');",
                  "    pm.expect(a).to.have.property('image');",
                  "});"
                ]
              }
            }
          ]
        },
        {
          "name": "Search articles",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/articles/search?q=gold&page_size=10",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "articles",
                "search"
              ],
              "query": [
                {
                  "key": "q",
                  "value": "gold",
                  "description": "at least 2 characters"
                },
                {
                  "key": "page_size",
                  "value": "10",
                  "description": "1\u2013100, default 20"
                },
                {
                  "key": "section",
                  "value": "education",
                  "description": "narrow to one section",
                  "disabled": true
                },
                {
                  "key": "sort",
                  "value": "newest",
                  "description": "newest | oldest | title",
                  "disabled": true
                }
              ]
            },
            "description": "Matches the query against title and excerpt. Same response shape as Latest articles."
          },
          "response": []
        },
        {
          "name": "One full article",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/articles/{{articleSlug}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "articles",
                "{{articleSlug}}"
              ],
              "query": []
            },
            "description": "Everything in the list shape, plus `body_html`, `body_text`, `word_count` and the SEO block.\n\n`{{articleSlug}}` is set for you by **Latest articles** \u2014 send that one first, or paste a slug into the collection variable."
          },
          "response": [],
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const body = pm.response.json();",
                  "pm.test('full text is present', () => {",
                  "    pm.expect(body.body_html).to.be.a('string');",
                  "    pm.expect(body.body_text).to.be.a('string');",
                  "    pm.expect(body.word_count).to.be.a('number');",
                  "});"
                ]
              }
            }
          ]
        },
        {
          "name": "Several full articles",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/articles/batch?slugs={{articleSlug}}",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "articles",
                "batch"
              ],
              "query": [
                {
                  "key": "slugs",
                  "value": "{{articleSlug}}",
                  "description": "comma-separated, maximum 20"
                }
              ]
            },
            "description": "Up to twenty full articles in one round trip \u2014 for backfilling a watchlist without twenty requests."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Tickers",
      "description": "Every fund is identified by ticker plus ISO-2 listing country. Cross-listings are separate entries \u2014 AGIX-US and AGIX-AE are the same strategy on two exchanges, never collapsed.",
      "item": [
        {
          "name": "Funds we cover",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/tickers?page_size=25",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "tickers"
              ],
              "query": [
                {
                  "key": "page_size",
                  "value": "25",
                  "description": "1\u2013100, default 50"
                },
                {
                  "key": "page",
                  "value": "1",
                  "description": "default 1",
                  "disabled": true
                },
                {
                  "key": "country",
                  "value": "AE",
                  "description": "ISO-2 listing country",
                  "disabled": true
                },
                {
                  "key": "with_articles",
                  "value": "true",
                  "description": "only funds that have coverage",
                  "disabled": true
                }
              ]
            },
            "description": "Every fund on the site, each with how many articles name it and when the most recent one ran."
          },
          "response": []
        },
        {
          "name": "Search funds",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/tickers/search?q=gold",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "tickers",
                "search"
              ],
              "query": [
                {
                  "key": "q",
                  "value": "gold",
                  "description": "ticker fragment or part of a fund name"
                },
                {
                  "key": "page_size",
                  "value": "25",
                  "description": "1\u2013100",
                  "disabled": true
                }
              ]
            },
            "description": "Matches against ticker and fund name."
          },
          "response": []
        },
        {
          "name": "Which funds have articles",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/tickers/with-coverage?page_size=25",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "tickers",
                "with-coverage"
              ],
              "query": [
                {
                  "key": "page_size",
                  "value": "25",
                  "description": "1\u2013100, default 100"
                }
              ]
            },
            "description": "Only funds we have written about, busiest first. The direct answer to \"which of my instruments have news\".\n\n`article_count` here always equals `meta.total_items` from **Articles about one fund** for the same ticker."
          },
          "response": [],
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const body = pm.response.json();",
                  "if (body.items && body.items.length) {",
                  "    pm.collectionVariables.set('ticker', body.items[0].ticker);",
                  "}"
                ]
              }
            }
          ]
        },
        {
          "name": "Articles about one fund",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/tickers/{{ticker}}/articles?page_size=10",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "tickers",
                "{{ticker}}",
                "articles"
              ],
              "query": [
                {
                  "key": "page_size",
                  "value": "10",
                  "description": "1\u2013100, default 20"
                }
              ]
            },
            "description": "Every article naming this fund, newest first. Same shape as Latest articles.\n\n`{{ticker}}` is set for you by **Which funds have articles**."
          },
          "response": []
        }
      ]
    },
    {
      "name": "Reference",
      "description": "Small, slow-moving lists you can cache for a day.",
      "item": [
        {
          "name": "Who this key is",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/meta",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "meta"
              ],
              "query": []
            },
            "description": "Confirms the key works and reports its scopes and rate limit. **Send this first** when wiring up."
          },
          "response": [],
          "event": [
            {
              "listen": "test",
              "script": {
                "type": "text/javascript",
                "exec": [
                  "const body = pm.response.json();",
                  "pm.test('key is recognised', () => {",
                  "    pm.expect(body).to.have.property('name');",
                  "    pm.expect(body.scopes).to.include('content:read');",
                  "});",
                  "console.log('Key: ' + body.name + ' | ' +",
                  "    body.rate_limit_per_minute + ' req/min | API ' + body.api_version);"
                ]
              }
            }
          ]
        },
        {
          "name": "Editorial sections",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/sections",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "sections"
              ],
              "query": []
            },
            "description": "The six sections an article can belong to."
          },
          "response": []
        },
        {
          "name": "Editorial tags",
          "request": {
            "method": "GET",
            "header": [],
            "url": {
              "raw": "{{baseUrl}}/tags",
              "host": [
                "{{baseUrl}}"
              ],
              "path": [
                "tags"
              ],
              "query": []
            },
            "description": "Every tag in use, for the `tag` filter on Latest articles."
          },
          "response": []
        }
      ]
    }
  ]
}
