DEV Community

Mayank Mahaur
Mayank Mahaur

Posted on

Bridging API Workspaces and AI Memory: Building a Postman Connector for Cognee

#ai #mergetober #opensource

Introduction

Modern software teams manage hundreds of microservices and third-party APIs. Postman collections are the de facto living documentation for these services, housing endpoint routes, authorization requirements, request bodies, query parameters, and sample responses.

However, AI agents and LLMs typically cannot access this institutional knowledge directly. Developers find themselves manually copying cURL commands and JSON payloads into ChatGPT prompts to ask: "What headers does our payment webhook require?" or "Which endpoint handles partial refunds?"

In this article, we explore how we built the official Postman data-source connector for Cognee during Mergetober 2026. This connector automatically ingests Postman collections into Cognee, turning static API documentation into queryable AI knowledge graphs with incremental sync and upstream deletion handling.

What is Cognee?

Cognee is an open-source memory layer for AI agents. Rather than dumping raw text into a stateless vector store, Cognee processes data through three distinct stages:

  1. cognee.add(data): Stages documents or structured records.
  2. cognee.cognify(): Parses content with an LLM to extract domain entities and relationships, constructing a persistent knowledge graph.
  3. cognee.search(query): Queries the interconnected graph and vector indexes to retrieve precise contextual memory.

To ingest external systems, Cognee relies on data-source connectors built on top of dlt (data load tool) sources.

The Architecture: How the Postman Connector Works 

[Postman API v10]
       |
       v
 [PostmanClient] ---> (Rate-limit backoff and 429 Retry-After handling)
       |
       v
[Sync Engine (postman.py)] ---> (State cache checks collection updatedAt)
       |
       +-> Unchanged? ---> Re-yield cached rows (0 detail network requests)
       |
       +-> Modified?  ---> Fetch collection schema and render documents
                                |
                                v
                   [Markdown Renderer (renderer.py)]
                                | (Folder breadcrumbs, parameter tables, schemas)
                                v
                    [@dlt.resource (postman_documents)]
                                | (Tagged: DOCUMENT_SOURCE_ATTR = "postman")
                                v
                          [cognee.add]
                                |
                                v
                        [cognee.cognify]
                                |
                                v
               [Unified Knowledge Graph & Vector Memory]
Enter fullscreen mode Exit fullscreen mode

Connecting Postman to Cognee requires solving three core architectural challenges:

1. Flattening Deeply Nested JSON Trees

Postman collections are hierarchical trees: collections contain folders, folders contain subfolders, and items contain requests and responses. Ingesting this as raw JSON would cause Cognee's graph pipeline to mirror the JSON syntax rather than extracting meaningful API entities.

Our markdown renderer (renderer.py) walks the tree up to 50 levels deep, transforming each endpoint into a discrete Markdown document:

  • Breadcrumbs: Explicit folder path navigation (e.g. Orders > Fulfillment > Ship Package).
  • HTTP Method & Route: Clear heading structure ([POST] /v1/orders/{id}/fulfill).
  • Parameter Tables: Formatted Markdown tables for headers, path parameters, and query parameters.
  • Payload Schemas: Syntax-highlighted JSON, GraphQL, and form-data definitions.
  • Sample Responses: Documented status codes (200, 400, 404) and example JSON bodies.

Each request becomes an independent node in Cognee's graph, tagged with a deterministic composite ID (f"{collection_uid}:{item_id}").

2. High-Efficiency Incremental Synchronization

Hitting Postman's REST API on every sync cycle quickly exhausts rate limits.

The connector tracks collection updatedAt metadata using dlt.current.resource_state(). On subsequent runs:

  • If a collection's updatedAt timestamp has not changed, the connector bypasses the detail API call entirely (0 API requests) and re-yields document rows directly from the state cache.
  • If a collection has been updated, only that modified collection is re-fetched and re-rendered.

3. Forget-on-Delete via Full-Snapshot Semantics

When an API collection is deleted or unshared in Postman, an AI agent should not continue answering questions based on obsolete endpoints.

By declaring write_disposition="replace" on the @dlt.resource and tagging DOCUMENT_SOURCE_ATTR = "postman", the active snapshot only contains currently visible collections. Any removed collection falls out of staging, prompting Cognee's built-in orphan_cleanup to purge outdated nodes and relations from the knowledge graph.

Production Code Standards

Building for open-source production requires rigorous engineering discipline:

  1. Resilient HTTP Client (client.py):
    • Automatic exponential backoff with jitter.
    • Native parsing of Retry-After headers on HTTP 429 rate limits.
    • Fallback error parsing handling HTML 502/500 gateways.
  2. Deterministic Hashing:
    • RFC 4122 UUIDv5 fallback keys for items without explicit IDs.
    • Volatile timestamps (createdAt, updatedAt) are excluded from document bodies to prevent content_hash churn in Cognee.
  3. Zero Emdash Invariant:
    • Automated text sanitization ensures complete compliance with repository typographic guidelines.
  4. Offline Test Suite (test_postman.py):
    • 180 unit tests spanning 4 tiers, running 100% offline in 0.62 seconds.

Quickstart: Seeing It In Action

You can run the connector out of the box in demonstration mode without a live Postman account:

import asyncio
from cognee_community_connector_postman import postman_source

async def main():
    # Initialize the source (falls back to sample Order API in demo mode)
    source = postman_source()

    # Cycle 1: Ingest documents
    documents = list(source)
    print(f"Ingested {len(documents)} endpoint documents into Cognee staging.")

    # Inspect a document
    doc = documents[0]
    print(f"ID: {doc['id']}")
    print(f"Title: {doc['title']}")
    print(doc["content"])

if __name__ == "__main__":
    asyncio.run(main())
Enter fullscreen mode Exit fullscreen mode

When connecting to live Postman workspaces, simply set your API key:

export POSTMAN_API_KEY="your-postman-api-key"
Enter fullscreen mode Exit fullscreen mode

Then add and cognify in Cognee:

import cognee
from cognee_community_connector_postman import postman_source

async def ingest_api_docs():
    source = postman_source()
    await cognee.add(source)
    await cognee.cognify()

    # Query your API documentation
    results = await cognee.search("How do I authenticate refund requests?")
    print(results)
Enter fullscreen mode Exit fullscreen mode

Conclusion & Mergetober Reflections

Participating in Mergetober 2026 has been an incredible opportunity to expand Cognee's data ecosystem. By connecting Postman collections directly into Cognee's memory layer, developers can now build intelligent coding assistants, automated API auditors, and documentation agents that genuinely understand their services.

Check out the code in the cognee-community repository under packages/connector/postman/!

Published for Mergetober 2026 by WeMakeDevs and Cognee

Top comments (0)