Skip to content

Commit 5b7c148

Browse files
htahir1htahir1
committed
Update API documentation to improve clarity and consistency
1 parent 5ecddd9 commit 5b7c148

File tree

13 files changed

+258
-289
lines changed

13 files changed

+258
-289
lines changed

‎docs/book/api-docs/README.md‎

Lines changed: 1 addition & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -2,58 +2,12 @@
22
description: The ZenML API Documentation
33
---
44

5-
# About
5+
# Introduction
66

77
## ZenML API Documentation
88

99
Welcome to the ZenML API documentation. This guide provides information about both the open-source (OSS) and Pro API endpoints available in the ZenML platform.
1010

11-
## Getting Started
12-
13-
To begin using the ZenML Server API, follow these simple steps:
14-
15-
{% stepper %}
16-
{% step %}
17-
### Setup
18-
19-
Ensure you have an active ZenML server or workspace configured.
20-
{% endstep %}
21-
22-
{% step %}
23-
### Authentication
24-
25-
Obtain an API token from your service account, as detailed in our core documentation.
26-
27-
{% tabs %}
28-
{% tab title="OSS API" %}
29-
* Obtain an API token from your service account
30-
* Include the token in the authorization header: `Authorization: Bearer YOUR_API_TOKEN`
31-
{% endtab %}
32-
33-
{% tab title="Pro API" %}
34-
Use your Pro API key in the authorization header: `Authorization: Bearer YOUR_API_KEY`
35-
{% endtab %}
36-
{% endtabs %}
37-
38-
39-
{% endstep %}
40-
41-
{% step %}
42-
### **API Access**
43-
44-
Use the token to authenticate and start interacting with the API endpoints.
45-
{% endstep %}
46-
{% endstepper %}
47-
48-
## API Endpoints Overview
49-
50-
The API provides several endpoints to facilitate different operations such as:
51-
52-
* **Pipelines**: Create, list, and manage your pipelines.
53-
* **Stacks**: Access and configure stack components, such as orchestrators, artifact stores, and more.
54-
* **Monitoring**: Retrieve logs and metrics to monitor the health of your operations.
55-
* **Pro Features**: For Pro users, access extended capabilities like organizations, tenants, and enterprise features.
56-
5711
## Use Cases
5812

5913
While the ZenML Python SDK covers most workflow requirements, the Server API offers additional utility for:
@@ -65,6 +19,3 @@ While the ZenML Python SDK covers most workflow requirements, the Server API off
6519

6620
By leveraging the ZenML API, users can enhance the robustness and control of their machine learning workflows, ensuring operations are both efficient and scalable.
6721

68-
***
69-
70-
For detailed information on each endpoint and further usage examples, please refer to the specific API documentation sections.

‎docs/book/api-docs/oss-api/oss-api/README.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,168 @@
11
# OSS API
22

3+
The ZenML OSS server is a FastAPI application, therefore the OpenAPI-compliant docs are available at `/docs` or `/redoc`
4+
of your ZenML server:
5+
6+
{% hint style="info" %}
7+
In the local case (i.e. using `zenml login --local`, the docs are available on `http://127.0.0.1:8237/docs`)
8+
{% endhint %}
9+
10+
![ZenML API docs](../.gitbook/assets/zenml_api_docs.png)
11+
12+
![ZenML API Redoc](../.gitbook/assets/zenml_api_redoc.png)
13+
14+
15+
## Accessing the ZenML OSS API
16+
17+
If you are using the ZenML OSS server API using the methods displayed above, it is enough to be logged in to your ZenML account in the same browser session. However, in order to do this programmatically, you can use one of the methods documented in the following sections.
18+
19+
### Using a short-lived API token
20+
21+
You can generate a short-lived (1 hour) API token from your ZenML dashboard. This is useful when you need a fast way to make authenticated HTTP requests to the ZenML API endpoints and you don't need a long-term solution.
22+
23+
1. Generate a short-lived API token through the API Tokens page under your ZenML dashboard server settings, as documented in the [Using an API token](../how-to/manage-zenml-server/connecting-to-zenml/connect-with-an-api-token.md) guide.
24+
25+
2. Use the API token as the bearer token in your HTTP requests. For example, you can use the following command to check your current user:
26+
* using curl:
27+
```bash
28+
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://your-zenml-server/api/v1/current-user
29+
```
30+
* using wget:
31+
```bash
32+
wget -qO- --header="Authorization: Bearer YOUR_API_TOKEN" https://your-zenml-server/api/v1/current-user
33+
```
34+
* using python:
35+
```python
36+
import requests
37+
38+
response = requests.get(
39+
"https://your-zenml-server/api/v1/current-user",
40+
headers={"Authorization": f"Bearer YOUR_API_TOKEN"}
41+
)
42+
print(response.json())
43+
```
44+
45+
{% hint style="info" %}
46+
**Important Notes**
47+
48+
- API tokens expire after 1 hour and cannot be retrieved after the initial generation
49+
- Tokens are scoped to your user account and inherit your permissions
50+
- For long-term programmatic access, it is recommended to [set up a service account and an API key](#using-a-service-account-and-an-api-key) instead
51+
{% endhint %}
52+
53+
54+
### Using a service account and an API key
55+
56+
You can use a service account's API key to obtain short-lived API tokens for programmatic access to the ZenML server's REST API. This is particularly useful when you need a long-term, secure way to make authenticated HTTP requests to the ZenML API endpoints.
57+
58+
1. Create a [service account](../how-to/manage-zenml-server/connecting-to-zenml/connect-with-a-service-account.md):
59+
```shell
60+
zenml service-account create myserviceaccount
61+
```
62+
63+
This will print out the `<ZENML_API_KEY>`, you can use in the next steps.
64+
65+
2. To obtain an API token using your API key, send a POST request to the `/api/v1/login` endpoint. Here are examples using common HTTP clients:
66+
* using curl:
67+
```bash
68+
curl -X POST -d "password=<YOUR_API_KEY>" https://your-zenml-server/api/v1/login
69+
```
70+
* using wget:
71+
```bash
72+
wget -qO- --post-data="password=<YOUR_API_KEY>" \
73+
--header="Content-Type: application/x-www-form-urlencoded" \
74+
https://your-zenml-server/api/v1/login
75+
```
76+
* using python:
77+
```python
78+
import requests
79+
import json
80+
81+
response = requests.post(
82+
"https://your-zenml-server/api/v1/login",
83+
data={"password": "<YOUR_API_KEY>"},
84+
headers={"Content-Type": "application/x-www-form-urlencoded"}
85+
)
86+
87+
print(response.json())
88+
```
89+
90+
This will return a response like this:
91+
92+
```json
93+
{
94+
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3MGJjZTg5NC1hN2VjLTRkOTYtYjE1Ny1kOTZkYWY5ZWM2M2IiLCJpc3MiOiJmMGQ5NjI1Ni04YmQyLTQxZDctOWVjZi0xMmYwM2JmYTVlMTYiLCJhdWQiOiJmMGQ5NjI1Ni04YmQyLTQxZDctOWVjZi0xMmYwM2JmYTVlMTYiLCJleHAiOjE3MTk0MDk0NjAsImFwaV9rZXlfaWQiOiIzNDkyM2U0NS0zMGFlLTRkMjctODZiZS0wZGRhNTdkMjA5MDcifQ.ByB1ngCPtBenGE6UugsWC6Blga3qPqkAiPJUSFDR-u4",
95+
"token_type": "bearer",
96+
"expires_in": 3600,
97+
"refresh_token": null,
98+
"scope": null
99+
}
100+
```
101+
102+
3. Once you have obtained an API token, you can use it to authenticate your API requests by including it in the `Authorization` header. For example, you can use the following command to check your current user:
103+
* using curl:
104+
```bash
105+
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://your-zenml-server/api/v1/current-user
106+
```
107+
* using wget:
108+
```bash
109+
wget -qO- --header="Authorization: Bearer YOUR_API_TOKEN" https://your-zenml-server/api/v1/current-user
110+
```
111+
* using python:
112+
```python
113+
import requests
114+
115+
response = requests.get(
116+
"https://your-zenml-server/api/v1/current-user",
117+
headers={"Authorization": f"Bearer {YOUR_API_TOKEN}"}
118+
)
119+
120+
print(response.json())
121+
```
122+
123+
{% hint style="info" %}
124+
**Important notes**
125+
126+
* API tokens are scoped to the service account that created them and inherit their permissions
127+
* Tokens are temporary and will expire after a configured duration (typically 1 hour, but it depends on how the server is configured)
128+
* You can request a new token at any time using the same API key
129+
* For security reasons, you should handle API tokens carefully and never share them
130+
* If your API key is compromised, you can rotate it using the ZenML dashboard or by running the `zenml service-account api-key <SERVICE_ACCOUNT_NAME> rotate` command
131+
{% endhint %}
132+
133+
## Getting Started
134+
135+
To begin using the ZenML Server API, follow these simple steps:
136+
137+
{% stepper %}
138+
{% step %}
139+
### Setup
140+
141+
Ensure you have an active ZenML server or workspace configured.
142+
{% endstep %}
143+
144+
{% step %}
145+
### Authentication
146+
147+
Obtain an API token from your service account, as detailed in our core documentation.
148+
149+
{% tabs %}
150+
{% tab title="OSS API" %}
151+
* Obtain an API token from your service account
152+
* Include the token in the authorization header: `Authorization: Bearer YOUR_API_TOKEN`
153+
{% endtab %}
154+
155+
{% tab title="Pro API" %}
156+
Use your Pro API key in the authorization header: `Authorization: Bearer YOUR_API_KEY`
157+
{% endtab %}
158+
{% endtabs %}
159+
160+
161+
{% endstep %}
162+
163+
{% step %}
164+
### **API Access**
165+
166+
Use the token to authenticate and start interacting with the API endpoints.
167+
{% endstep %}
168+
{% endstepper %}

‎docs/book/api-docs/pro-api/pro-api/README.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,35 @@
11
# Pro API
22

3+
The ZenML Pro API extends the open-source API with additional features designed for enterprise users, including:
4+
5+
- Enhanced team collaboration features
6+
- Advanced role-based access control
7+
- Enterprise-grade security features
8+
9+
To access the Pro API, you need a ZenML Pro license. Refer to the [Pro API documentation](https://docs.zenml.io/api-reference/pro-api/pro-api/api-reference) for detailed information on the available endpoints and features.
10+
11+
### Accessing the ZenML Pro API
12+
13+
The ZenML Pro API is distinct from the OSS server API:
14+
15+
- The SaaS version of ZenML Pro API is hosted at [https://cloudapi.zenml.io](https://cloudapi.zenml.io)
16+
- You can access the API docs directly at [https://cloudapi.zenml.io](https://cloudapi.zenml.io)
17+
- If you're logged into your ZenML Pro account at [https://cloud.zenml.io](https://cloud.zenml.io), you can use the same browser session to authenticate requests directly in the OpenAPI docs
18+
19+
### Pro API Authentication
20+
21+
To programmatically access the ZenML Pro API:
22+
23+
1. Navigate to the organization settings page in your ZenML Pro dashboard
24+
2. Select "API Tokens" from the left sidebar
25+
3. Click the "Create new token" button to generate a new API token
26+
4. Use the API token as the bearer token in your HTTP requests:
27+
28+
```bash
29+
# Example of accessing the Pro API
30+
curl -H "Authorization: Bearer YOUR_API_TOKEN" https://cloudapi.zenml.io/users/me
31+
```
32+
33+
Note that for workspace programmatic access, you can use the same methods described below for the OSS API (temporary API tokens or service accounts).
34+
35+
For full details on using the ZenML Pro API, including available endpoints and features, see the [Pro API guide](https://docs.zenml.io/pro/deployments/pro-api).

‎docs/book/api-docs/toc.md‎

Lines changed: 51 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# Table of contents
22

3-
* [About](README.md)
3+
* [Introduction](README.md)
44

55
## OSS API
66

@@ -51,58 +51,57 @@
5151
* [Users](oss-api-docs/v1/users/README.md)
5252
* [Resource membership](oss-api-docs/v1/users/resource-membership.md)
5353
* [Current user](oss-api-docs/v1/current-user.md)
54-
* [OSS API Specification](https://1cf18d95-zenml.cloudinfra.zenml.io/openapi.json)
54+
* [OSS API Specification](https://1cf18d95-zenml.cloudinfra.zenml.io/openapi.json)
5555

5656
## Pro API
5757

5858
* [Pro API](pro-api/pro-api/README.md)
59-
* [API reference](pro-api-docs/api-reference/README.md)
60-
* [Tenants](pro-api-docs/api-reference/tenants/README.md)
61-
* [Deploy](pro-api-docs/api-reference/tenants/deploy.md)
62-
* [Deactivate](pro-api-docs/api-reference/tenants/deactivate.md)
63-
* [Members](pro-api-docs/api-reference/tenants/members.md)
64-
* [Tenant status](pro-api-docs/api-reference/tenant-status.md)
65-
* [Users](pro-api-docs/api-reference/users/README.md)
66-
* [Authorize server](pro-api-docs/api-reference/users/authorize-server.md)
67-
* [Me](pro-api-docs/api-reference/users/me.md)
68-
* [Invitations](pro-api-docs/api-reference/invitations.md)
69-
* [Releases](pro-api-docs/api-reference/releases.md)
70-
* [Devices](pro-api-docs/api-reference/devices/README.md)
71-
* [Verify](pro-api-docs/api-reference/devices/verify.md)
72-
* [Roles](pro-api-docs/api-reference/roles/README.md)
73-
* [Assignments](pro-api-docs/api-reference/roles/assignments.md)
74-
* [Permissions](pro-api-docs/api-reference/permissions.md)
75-
* [Teams](pro-api-docs/api-reference/teams/README.md)
76-
* [Members](pro-api-docs/api-reference/teams/members.md)
77-
* [Organizations](pro-api-docs/api-reference/organizations/README.md)
78-
* [Trial](pro-api-docs/api-reference/organizations/trial.md)
79-
* [Invitations](pro-api-docs/api-reference/organizations/invitations.md)
80-
* [Members](pro-api-docs/api-reference/organizations/members.md)
81-
* [Roles](pro-api-docs/api-reference/organizations/roles.md)
82-
* [Teams](pro-api-docs/api-reference/organizations/teams.md)
83-
* [Tenants](pro-api-docs/api-reference/organizations/tenants.md)
84-
* [Tenant](pro-api-docs/api-reference/organizations/tenant.md)
85-
* [Entitlement](pro-api-docs/api-reference/organizations/entitlement.md)
86-
* [Validation](pro-api-docs/api-reference/organizations/validation/README.md)
87-
* [Name](pro-api-docs/api-reference/organizations/validation/name.md)
88-
* [Tenant name](pro-api-docs/api-reference/organizations/validation/tenant-name.md)
89-
* [Health](pro-api-docs/api-reference/health.md)
90-
* [Usage event](pro-api-docs/api-reference/usage-event.md)
91-
* [Usage batch](pro-api-docs/api-reference/usage-batch.md)
92-
* [Stigg webhook](pro-api-docs/api-reference/stigg-webhook.md)
93-
* [Auth](pro-api-docs/api-reference/auth/README.md)
94-
* [Login](pro-api-docs/api-reference/auth/login.md)
95-
* [Connections](pro-api-docs/api-reference/auth/connections.md)
96-
* [Authorize](pro-api-docs/api-reference/auth/authorize.md)
97-
* [Callback](pro-api-docs/api-reference/auth/callback.md)
98-
* [Logout](pro-api-docs/api-reference/auth/logout.md)
99-
* [Device authorization](pro-api-docs/api-reference/auth/device-authorization.md)
100-
* [Api token](pro-api-docs/api-reference/auth/api-token.md)
101-
* [Tenant authorization](pro-api-docs/api-reference/auth/tenant-authorization.md)
102-
* [Rbac](pro-api-docs/api-reference/rbac/README.md)
103-
* [Check permissions](pro-api-docs/api-reference/rbac/check-permissions.md)
104-
* [Allowed resource ids](pro-api-docs/api-reference/rbac/allowed-resource-ids.md)
105-
* [Resource members](pro-api-docs/api-reference/rbac/resource-members.md)
106-
* [Server](pro-api-docs/api-reference/server/README.md)
107-
* [Info](pro-api-docs/api-reference/server/info.md)
108-
* [Pro API Specification](https://cloudapi.zenml.io/openapi.json)
59+
* [Tenants](pro-api-docs/api-reference/tenants/README.md)
60+
* [Deploy](pro-api-docs/api-reference/tenants/deploy.md)
61+
* [Deactivate](pro-api-docs/api-reference/tenants/deactivate.md)
62+
* [Members](pro-api-docs/api-reference/tenants/members.md)
63+
* [Tenant status](pro-api-docs/api-reference/tenant-status.md)
64+
* [Users](pro-api-docs/api-reference/users/README.md)
65+
* [Authorize server](pro-api-docs/api-reference/users/authorize-server.md)
66+
* [Me](pro-api-docs/api-reference/users/me.md)
67+
* [Invitations](pro-api-docs/api-reference/invitations.md)
68+
* [Releases](pro-api-docs/api-reference/releases.md)
69+
* [Devices](pro-api-docs/api-reference/devices/README.md)
70+
* [Verify](pro-api-docs/api-reference/devices/verify.md)
71+
* [Roles](pro-api-docs/api-reference/roles/README.md)
72+
* [Assignments](pro-api-docs/api-reference/roles/assignments.md)
73+
* [Permissions](pro-api-docs/api-reference/permissions.md)
74+
* [Teams](pro-api-docs/api-reference/teams/README.md)
75+
* [Members](pro-api-docs/api-reference/teams/members.md)
76+
* [Organizations](pro-api-docs/api-reference/organizations/README.md)
77+
* [Trial](pro-api-docs/api-reference/organizations/trial.md)
78+
* [Invitations](pro-api-docs/api-reference/organizations/invitations.md)
79+
* [Members](pro-api-docs/api-reference/organizations/members.md)
80+
* [Roles](pro-api-docs/api-reference/organizations/roles.md)
81+
* [Teams](pro-api-docs/api-reference/organizations/teams.md)
82+
* [Tenants](pro-api-docs/api-reference/organizations/tenants.md)
83+
* [Tenant](pro-api-docs/api-reference/organizations/tenant.md)
84+
* [Entitlement](pro-api-docs/api-reference/organizations/entitlement.md)
85+
* [Validation](pro-api-docs/api-reference/organizations/validation/README.md)
86+
* [Name](pro-api-docs/api-reference/organizations/validation/name.md)
87+
* [Tenant name](pro-api-docs/api-reference/organizations/validation/tenant-name.md)
88+
* [Health](pro-api-docs/api-reference/health.md)
89+
* [Usage event](pro-api-docs/api-reference/usage-event.md)
90+
* [Usage batch](pro-api-docs/api-reference/usage-batch.md)
91+
* [Stigg webhook](pro-api-docs/api-reference/stigg-webhook.md)
92+
* [Auth](pro-api-docs/api-reference/auth/README.md)
93+
* [Login](pro-api-docs/api-reference/auth/login.md)
94+
* [Connections](pro-api-docs/api-reference/auth/connections.md)
95+
* [Authorize](pro-api-docs/api-reference/auth/authorize.md)
96+
* [Callback](pro-api-docs/api-reference/auth/callback.md)
97+
* [Logout](pro-api-docs/api-reference/auth/logout.md)
98+
* [Device authorization](pro-api-docs/api-reference/auth/device-authorization.md)
99+
* [Api token](pro-api-docs/api-reference/auth/api-token.md)
100+
* [Tenant authorization](pro-api-docs/api-reference/auth/tenant-authorization.md)
101+
* [Rbac](pro-api-docs/api-reference/rbac/README.md)
102+
* [Check permissions](pro-api-docs/api-reference/rbac/check-permissions.md)
103+
* [Allowed resource ids](pro-api-docs/api-reference/rbac/allowed-resource-ids.md)
104+
* [Resource members](pro-api-docs/api-reference/rbac/resource-members.md)
105+
* [Server](pro-api-docs/api-reference/server/README.md)
106+
* [Info](pro-api-docs/api-reference/server/info.md)
107+
* [Pro API Specification](https://cloudapi.zenml.io/openapi.json)

‎docs/book/component-guide/.gitbook.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -268,4 +268,4 @@ redirects:
268268
how-to/pipeline-development/trigger-pipelines/use-templates-python: how-to/trigger-pipelines/use-templates-python.md
269269
how-to/pipeline-development/trigger-pipelines/use-templates-cli: how-to/trigger-pipelines/use-templates-cli.md
270270
how-to/pipeline-development/trigger-pipelines/use-templates-dashboard: how-to/trigger-pipelines/use-templates-dashboard.md
271-
how-to/pipeline-development/trigger-pipelines/use-templates-rest-api: how-to/trigger-pipelines/use-templates-rest-api.md
271+
how-to/pipeline-development/trigger-pipelines/use-templates-rest-api: how-to/trigger-pipelines/use-templates-rest-api.md

0 commit comments

Comments
 (0)