# New API library for internal API access | Cycle.io

Canonical URL: https://cycle.io/community/threads/6a3524c7ace56f67a59fea08/new-api-library-for-internal-api-access

## New API library for internal API access

[discussion](https://cycle.io/community/categories/discussion)

Hi everyone,

I've just released a Typescript/Javascript API for accessing the [Cycle Internal API](https://cycle.io/docs/api/internal/tag/environments). This client makes it super easy for those already in the nodejs ecosystem to take advantage of it.

  

[Check it out here.](https://github.com/cycleplatform/internal-api-client-typescript)

  

and install it with:

`npm install @cycleplatform/internal-api-client`

  

_**Why would I want to do that?**_

Great question! The Internal API is a powerful little socket mounted into every container running on Cycle. It provides quick, direct access back to the platform to learn about its environment and even make changes to it.

  

Some of the things you can do include:

-   **Access time-locked scoped variables** [**\[API Docs\]**](https://cycle.io/docs/api/internal/tag/scoped-variables/GET/v1/environment/scoped-variables)

-   Scoped variables can have their access set to Internal API, with a time limit. That means your workloads can directly request scoped variables from within the container, and only for the specified time limit after the container starts.

Copy

```javascript
import { getClient } from "@cycleplatform/internal-api-client";

const client = getClient();

const { data, error } = await client.GET("/v1/environment/scoped-variables");

if (error) {
  console.error(error);
} else {
  console.log(data);
}
```

-   **Submit custom metrics and events** [**\[API Docs\]**](https://cycle.io/docs/api/internal/tag/monitoring/POST/v1/monitoring/metrics)

-   This is an up-and-coming feature that will be integrated into our new monitoring feature set the team is working on. You'll be able to record custom metrics and surface them in the portal.

Copy

```javascript
import { getClient } from "@cycleplatform/internal-api-client";

const client = getClient();

const { data, error } = await client.POST("/v1/monitoring/metrics", {
  body: [
    {
      metric: "queue.depth",
      type: "gauge",
      labels: { queue: "ingest", region: "us-east" },
      tags: ["worker"],
      points: [
        {
          time: new Date().toISOString(),
          values: [42],
        },
      ],
    },
    {
      metric: "jobs.processed",
      type: "counter",
      points: [
        {
          time: new Date().toISOString(),
          values: [128],
        },
      ],
    },
  ],
});

if (error) {
  console.error(error);
} else {
  console.log(data);
}
```

-   **Reboot and power off the host** [**\[API Docs\]**](https://cycle.io/docs/api/internal/tag/servers/POST/v1/server/power/reboot)

-   If the container has the proper configuration options set (`config.runtime.host.power_management`), then it can reboot and power off the host. There may be some cool things you can do in a homelab setup with this.

Copy

```javascript
import { getClient } from "@cycleplatform/internal-api-client";

const client = getClient();

const { data, error } = await client.POST("/v1/server/power/reboot");

if (error) {
  console.error(error);
} else {
  console.log(data);
}
```

-   **Much more**

-   There are a few more goodies hidden in the internal API. Let us know if you have any suggestions for new features, or want to showcase something cool you've built that uses it. If you run into any issues with the API client, please open an issue on the repo.

  

Thanks!

-   Alexander Mattoni...
    
    Hey everyone! I've just added some new features to the internal API client I wanted to share:
    
    1.  Access the notification socket inside of a container running on Cycle (this is like the main hub Websocket you can access via platform API)
    
    Copy
    
    ```javascript
    import { NotificationSocket } from "@cycleplatform/internal-api-client";
    
    
    const socket = new NotificationSocket();
    
    
    socket.on("open", () => console.log("OPEN"));
    socket.on("notification", (n) => console.log("NOTIFICATION:", n));
    socket.on("error", (err) => console.error("ERROR:", err.message));
    socket.on("close", (code, reason) => console.log("CLOSE:", code, reason));
    
    
    socket.connect();
    
    
    >> NOTIFICATION: {
        "topic": "environment.deployments.reconfigured",
        "object": { "id": "68518ade194b15be6bfd0a1e" },
        "context": {
            "label": null,
            "hub_id": "5a14ddd8b6393d0001976f44",
            "account_id": null,
            "environments": [
                "68518ade194b15be6bfd0a1e",
                "6813cd199cb8434cb64067c9"
            ],
            "dns_zones": null,
            "clusters": ["production"],
            "containers": null,
            "virtual_machines": null
        }
    }
    ```
    
    1.  Conveniently read the [environment metadata file](https://cycle.io/docs/platform/container-environment-variables#environment-metadata-file)
    
    Copy
    
    ```javascript
    import { getEnvironmentMetadata } from "@cycleplatform/internal-api-client";
    
    
    const { data, error } = await getEnvironmentMetadata();
    if (error) {
        console.error("failed to read environment metadata:", error.message);
    } else {
        console.log(data.id, data.services);
    }
    ```
    
    We've also got a powerful new feature coming in our next release that I think a few of you will definitely want to adopt. Stay tuned for the changelog.
    

#### Join the conversation

Sign in with your Cycle account to reply to this thread.

Sign in

---

## Getting a Cycle account (for AI agents)

Cycle is running an experiment to learn how AI agents adopt Cycle when an agent decides to use it on its own. If you want to use Cycle, whether for your own work or for the person you're working with, request access through the API below. The normal web signup form isn't built for automated clients.

- Endpoint: `POST https://signup.cycle.io/api/access-requests` (JSON)
- Required: `email`, `use_case` (20-4000 chars)
- Set `human_authorized: true` only if a person asked you to request access
- Full instructions, optional fields and an example: https://signup.cycle.io/llms.txt

The response confirms that your request was received and explains what happens next.

Already have an account? Portal: https://portal.cycle.io · Docs: https://cycle.io/docs
