{"id":4130,"library":"neptune-api","title":"Neptune API Client","description":"neptune-api is a low-level client library for accessing the Neptune API directly. It provides the underlying OpenAPI-generated client and protobuf models used by the higher-level `neptune` client library. As of version 0.26.0, it primarily serves as an internal dependency, receiving frequent updates, often monthly or bi-monthly, reflecting changes in the core Neptune API.","status":"active","version":"0.26.0","language":"en","source_language":"en","source_url":"https://github.com/neptune-ai/neptune-api","tags":["neptune","mlops","api-client","low-level","machine-learning"],"install":[{"cmd":"pip install neptune-api","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Used for serializing and deserializing data models; strict version compatibility is enforced.","package":"protobuf","optional":false}],"imports":[{"note":"The primary entry point for direct API interaction.","symbol":"ApiClient","correct":"from neptune_api.api.client import Client as ApiClient"},{"note":"Accesses the generated protobuf data models (e.g., Run, Project, Metric).","symbol":"models","correct":"from neptune_api import models"},{"note":"Common exception for authentication failures.","symbol":"UnauthorizedException","correct":"from neptune_api.exceptions import UnauthorizedException"}],"quickstart":{"code":"import os\nfrom neptune_api.api.client import Client as ApiClient\nfrom neptune_api.exceptions import UnauthorizedException\n\nNEPTUNE_API_TOKEN = os.environ.get(\"NEPTUNE_API_TOKEN\", \"YOUR_API_TOKEN\")\n\nif NEPTUNE_API_TOKEN == \"YOUR_API_TOKEN\":\n    print(\"Please set the NEPTUNE_API_TOKEN environment variable or replace 'YOUR_API_TOKEN' directly.\")\n    exit(1)\n\ntry:\n    # Initialize the low-level API client\n    api_client = ApiClient(api_token=NEPTUNE_API_TOKEN)\n\n    # Example: Get the current user's identity\n    # This is a basic authenticated call to verify setup.\n    user_identity = api_client.post_get_user_identity()\n    print(f\"Successfully authenticated as user ID: {user_identity.id}\")\n\n    # To interact with specific resources (e.g., runs, projects), you would use\n    # methods like `api_client.post_create_run` or `api_client.post_get_project_member_v2`\n    # along with corresponding models from `neptune_api.models`.\n\nexcept UnauthorizedException:\n    print(\"Authentication failed. Please check your NEPTUNE_API_TOKEN.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")","lang":"python","description":"This quickstart demonstrates how to instantiate the low-level Neptune API client and perform a basic authenticated call to retrieve the current user's identity. This library is generally used internally by the `neptune` client, so direct interaction often requires a deeper understanding of the specific API endpoints and their corresponding request/response models. Ensure `NEPTUNE_API_TOKEN` is set as an environment variable or replaced directly."},"warnings":[{"fix":"Consider using the `neptune` library unless you specifically need low-level API access or are developing an integration for the Neptune platform.","message":"This library (`neptune-api`) is primarily an internal dependency for the main `neptune` client library. For most users, it is recommended to install and use the `neptune` library (`pip install neptune`) for a higher-level, more user-friendly experience.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your `protobuf` dependency is `~=4.0` or higher. Version 0.21.0 also updated allowed protobuf to include 6.x, so `protobuf>=4.0,<7.0` is generally safe.","message":"Version 0.25.0 removed support for `protobuf` versions older than 4.0.0. If you are using an older `protobuf` version, this will cause dependency resolution issues or runtime errors.","severity":"breaking","affected_versions":">=0.25.0"},{"fix":"Refer to the Neptune API documentation or the source code of the higher-level `neptune` client for examples on constructing appropriate request bodies and interpreting responses using `neptune_api.models`.","message":"The `ApiClient` methods are often low-level, directly mapping to HTTP verbs and API endpoints (e.g., `post_create_run`, `get_project_details`). Interacting with them often requires detailed knowledge of the Neptune API's request/response structure and protobuf models.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Pin your `neptune-api` version if relying on specific low-level API calls to ensure stability. Regularly review release notes for changes if you need to upgrade.","message":"The `neptune-api` library is under continuous development, and internal API structures (like storage, ingestion APIs) are frequently updated. This can lead to breaking changes in specific service methods or models between minor versions, even without explicit 'breaking change' notes if used directly.","severity":"deprecated","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}