Cogniac Python SDK

Python SDK for the Cogniac public API. Provides both synchronous and asynchronous (async/await) interfaces.

Requires Python 3.11+

Installation

pip install cogniac

Configuration

Authentication is configured via environment variables or constructor arguments:

Variable	Description
`COG_USER`	Cogniac username (usually an email address)
`COG_PASS`	Cogniac password
`COG_API_KEY`	API key (alternative to username/password)
`COG_TENANT`	Tenant ID (required if user belongs to multiple tenants)
`COG_URL_PREFIX`	API endpoint (default: `https://api.cogniac.io/`)

Synchronous API

import cogniac

cc = cogniac.CogniacConnection()

# Tenants and users
tenant = cc.get_tenant()
print(tenant.name)

# Applications
apps = cc.get_all_applications()
app = cc.get_application(application_id)

# Subjects
subjects = cc.get_all_subjects()
subject = cc.create_subject(name="my-subject", description="example")
subject.description = "updated"  # auto-syncs to API
subject.delete()

# Media
media = cc.create_media("image.jpg", meta_tags=["test"])
fetched = cc.get_media(media.media_id)
image_bytes = fetched.download()          # returns bytes
with open("out.jpg", "wb") as f:          # or write to file
    fetched.download(f)                   # takes open file object, NOT a path string

# Paginated results via generators
for detection in app.detections(limit=100):
    print(detection)

Entity Classes

Class	Description
`CogniacConnection`	Authentication and HTTP session management
`CogniacApplication`	Vision applications (detection, classification, etc.)
`CogniacSubject`	Organizational groupings of media
`CogniacMedia`	Image and video files
`CogniacTenant`	Tenant (organization) management
`CogniacUser`	User accounts and API keys
`CogniacEdgeFlow`	Edge computing devices (alias: `CogniacGateway`)
`CogniacNetworkCamera`	Network camera configuration
`CogniacExternalResult`	External inspection results
`CogniacOpsReview`	Operations review queue
`CogniacDeployment`	Deployment groups (EdgeFlow/CloudFlow rollouts)
`CogniacDeploymentCapacityClass`	Deployment capacity classes
`CogniacWorkflow`	Deployment workflows and versions
`CogniacBuild`	EdgeFlow/CloudFlow build definitions

Async API

The async interface mirrors the sync API. Use AsyncCogniacConnection.create() as an async factory:

import asyncio
import cogniac

async def main():
    async with await cogniac.AsyncCogniacConnection.create() as cc:
        # List subjects
        subjects = await cogniac.AsyncCogniacSubject.get_all(cc)
        for s in subjects:
            print(s.name, s.subject_uid)

        # Create and update
        s = await cogniac.AsyncCogniacSubject.create(cc, name="my-subject")
        await s.set(description="updated")  # explicit async setter
        await s.delete()

        # Download media
        media = await cogniac.AsyncCogniacMedia.get(cc, media_id)
        image_bytes = await media.download()      # returns bytes
        with open("out.jpg", "wb") as f:           # or write to file
            await media.download(f)                # takes open file object, NOT a path string

        # Async generators for paginated endpoints
        apps = await cogniac.AsyncCogniacApplication.get_all(cc)
        async for detection in apps[0].detections(limit=10):
            print(detection)

asyncio.run(main())

Every sync entity class has an async counterpart prefixed with Async (e.g., AsyncCogniacSubject, AsyncCogniacMedia).

Key Differences from Sync API

Connection: await AsyncCogniacConnection.create(...) instead of CogniacConnection(...)
Attribute updates: await subject.set(name="new") instead of subject.name = "new" (batches multiple fields in one API call)
Pagination: async for with generators (detections, media_associations, usage, etc.)
Cleanup: supports async with context manager for automatic session cleanup

CLI Tools

`cogniac`

Agent-friendly CLI. JSON output by default; --format table for humans or --format jsonl for one JSON object per line. The command tree is nested, noun-first / verb-last; resource ids are --<resource>-id flags (the older positional form, e.g. application get <id>, still works). --format and --tenant may be given before or after the command.

cogniac auth                                       # check credentials (add --tenant <id> to verify a session)
cogniac auth login                                 # browser login; store a per-user API key
cogniac commands                                   # print the whole command tree as JSON (noun -> verbs -> args)

cogniac tenant get                                 # current tenant info
cogniac application list                           # list applications
cogniac application get --application-id <id>      # one application
cogniac subject list
cogniac subject search --prefix test               # search subjects
cogniac subject media --subject-uid <uid> --full-media   # full media records, not just media_id
cogniac media get --media-id <id>                  # media metadata
cogniac media download --media-id <id> -o out.jpg  # download media to file
cogniac edgeflow list                              # list edge devices
cogniac edgeflow status --edgeflow-id <id> --list-subsystems   # discover which subsystems a device reports
cogniac edgeflow health                            # fleet health derived from each device's latest status record
cogniac application create --body @app.json        # --body takes inline JSON, @FILE, or - (stdin)

cogniac deployment deploy --deployment-group-id <id> --workflow-id <wf>   # DISPATCH a workflow rollout
                                                   # (--now bypasses the group schedule; --timeout raises the
                                                   #  client read timeout — the server blocks until every
                                                   #  EdgeFlow accepts, default 300s)
cogniac deployment deploy-status --deployment-group-id <id>               # rollout convergence status
cogniac deployment target workflow set ...         # records target_workflow_id only — does NOT deploy

Run cogniac <noun> --help to explore the tree interactively, or cogniac commands for the full machine-readable catalog. An unknown command suggests the closest match.

`icogniac`

Interactive IPython shell with pre-loaded Cogniac connection:

icogniac [optional tenant name or ID]

`cogupload`

Parallel media upload (24 threads) to a subject:

cogupload <subject_uid> <directory>

`cogstats`

EdgeFlow statistics aggregation:

cogstats -t TENANT_ID [-g GATEWAY_ID] [-s START] [-e END]

Support

Please email support@cogniac.co with feedback.

Release files for cogniac 3.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cogniac 3.3.0
File	Size	Uploaded
cogniac-3.3.0.tar.gz	164.1 kB	Jul 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for cogniac 3.3.0
File	Interpreter	ABI	Platform	Reset
cogniac-3.3.0-py3-none-any.whl 146.2 kB Jul 22, 2026	Python 3	none	any	Details

Total release size: 310.3 kB

Release files / cogniac-3.3.0.tar.gz

Download URL	cogniac-3.3.0.tar.gz
Size	164.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`a0d41a1fe2d9c73c42880a84941124f540c6c914c5c92580f68f73d762c467ef`
BLAKE2b-256 checksum How to use checksums	`1f21710816ae11ee3e11685132c353a71eb9e6e11b017fa8513d6365050fd065`
Upload date	Jul 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.5`

Release files / cogniac-3.3.0-py3-none-any.whl

Download URL	cogniac-3.3.0-py3-none-any.whl
Size	146.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`16380e946c4e291f5c64e9240d4366f395d61cf9bbec87836986e5b744615323`
BLAKE2b-256 checksum How to use checksums	`d1513b1d2f749dde1db5f10490867f93411e7c92182facfb9a52f4791d4e830a`
Upload date	Jul 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.14.5`