Docs

DCN Public API Tutorial

REST API for the Decentralised Creative Network. This guide explains how to authenticate, work with accounts, features and transformations, and execute features to generate data.

Base URL: https://api.decentralised.art Version: 1.0.0

Standard Parameters

Address

address - (0x + 40 hex)

Pagination

limit - integer
page - integer

Feature / Transformation IDs

featureName - string
featureVersion - optional
transformationName - string
transformationVersion - optional

Execution

numSamples - integer
runningInstances - string, e.g. [(0;12)(512;24)]

Standard Error Shape

Error responses use a common JSON format:

{
  "error": "string",
  "message": "string"
}

Status codes: 400 (Bad Request), 401 (Unauthorized), 404 (Not Found).

SDK

DCN exposes lightweight client libraries so you don't have to hand-craft every request. Use the SDKs to handle authentication, pagination and common operations like reading features, transformations and executing data.

Python SDK

Official Python client.

Repo (Python) : github.com/hypermusic-ai/dcn-sdk

JavaScript SDK (experimental)

Early JS/TypeScript client for browser and Node environments.

Repo (JS) : github.com/hypermusic-ai/dcn-sdk

Tip: you can mix raw HTTP (cURL) with SDK calls — the wire format is always the same OpenAPI contract.

Authentication & Security

The API uses JSON Web Tokens (JWT) in the Authorization header.

Authorization: Bearer <ACCESS_TOKEN>

Some flows use a refresh token X-Refresh-Token header:

X-Refresh-Token: <REFRESH_TOKEN>

Tokens are obtained via a nonce + signature flow using an Ethereum address.

Authentication Flow

1. Get nonce

Request a login nonce bound to an Ethereum address.

GET /nonce/{address}

2. Sign and authenticate

Sign the nonce, then send the signed message to /auth.

POST /auth 
        Content-Type: application/json
        {
            "address": "0x...",
            "message": "Login nonce: ...",
            "signature": "0x..."
        }

Response

{
  "access_token": "...",
  "refresh_token": "..."
}

3. Refresh access token

Refresh an access token using a refresh token.

POST /refresh
            X-Refresh-Token: <REFRESH_TOKEN>

Response

{
  "access_token": "...",
  "refresh_token": "..."
}

Usage


curl -X POST 
    -H "Content-Type: application/json" 
    -d '{"address": "0x...", "message": "Login nonce: ...", "signature": "0x..."}' 
    "https://api.decentralised.art/auth"

import dcn
from eth_account import Account

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Create an ephemeral account (or use your own private key)
acct = Account.create()

# Authenticate (nonce + ECDSA sign under the hood)
sdk_client.login_with_account(acct)

import { DcnClient } from '@hypermusic-ai/dcn-js';
import { Wallet } from 'ethers';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Create an ephemeral account (or use your own private key)
const wallet = Wallet.createRandom();

// Authenticate (nonce + ECDSA sign under the hood)
await sdkClient.loginWithWallet(wallet);

Version

Returns API version and build timestamp.

GET /version

Response

{
  "version": "...",
  "build_timestamp": "..."
}

Usage

curl -X GET "https://api.decentralised.art/version"

import dcn

# Client points to the public DCN API by default:
sdk_client = dcn.Client()

# Read API server version
version = sdk_client.version()

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
const sdkClient = new DcnClient();

// Read API server version
const response = await sdkClient.version();

Account

Get account metadata, including owned features and transformations (paged).

GET /account/{address}?limit=<limit>&page=<page>

Response

{
  "address": "0x...",
  "limit": <limit>,
  "page": <page>,
  "total_features": ...,
  "total_transformations": ...,
  "owned_features": [
    "...",
    ...
  ],
  "owned_transformations": [
    "...",
    ...
  ]
}

Usage


curl -X GET "https://api.decentralised.art/account/0x...?limit=...&page=..."

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Get account information
acc_info = sdk_client.account_info("0x...", limit = ..., page = ...)

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Get account information
const accInfo = await sdkClient.accountInfo("0x...", ..., ...);

Features

A feature is composed of one or more dimensions, each referencing a base feature and a chain of transformations.

{
  "address": "0x...",
  "dimensions": [
    {
      "feature_name": "...",
      "transformations": [
        { "name": "...", "args": [...] },
        ...      
      ]
    }
  ],
  "local_address": "0x...",
  "name": "...",
  "owner": "..."
}

Get the latest version of a feature by name.

GET /feature/<featureName>

Usage


curl -X GET "https://api.decentralised.art/feature/<featureName>"

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Obtain feature data
feature_info = sdk_client.feature_get("<featureName>")

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Obtain feature data
const featureInfo = await sdkClient.featureGet("<featureName>");

Get a specific version of a feature by name and version.

GET /feature/<featureName>/<featureVersion>

Usage


curl -X GET "https://api.decentralised.art/feature/<featureName>/<featureVersion>"

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Obtain specyfic feature data
feature_info = sdk_client.feature_get("<featureName>", "<featureVersion>")

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Obtain specyfic feature data
const featureInfo = await sdkClient.featureGet("<featureName>", "<featureVersion>");

Create/publish a new feature. Requires a valid bearer token.

POST /feature
        Authorization: Bearer <ACCESS_TOKEN>
        Content-Type: application/json
        {
            "name": "...",
            "dimensions": 
            [
                {
                    "feature_name": "...",
                    "transformations": 
                    [
                        { "name": "...", "args": [...] },
                        ...
                    ]
                },
                {
                    "feature_name": "...",
                    "transformations": [...]
                },
                ...
            ]
        }

Usage


curl -X POST 
    -H "Authorization: Bearer <ACCESS_TOKEN>"
    -H "Content-Type: application/json" 
    -d '{"name": "...", "dimensions": [...]}'
    "https://api.decentralised.art/feature"

import dcn
from eth_account import Account

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Create an ephemeral account (or use your own private key)
acct = Account.create()

# Authenticate (nonce + ECDSA sign under the hood)
sdk_client.login_with_account(acct)

# Create a feature with dimensions & transformations, need to be logged first
sdk_client.feature_post({
  "name": "...",
  "dimensions": [
    {
      "feature_name": "...",
      "transformations": [
        {"name": "...", "args": [...]},
        ...
      ]
    },
    {"feature_name": "...", "transformations": [...]},
    ...
  ]
})

import { DcnClient } from '@hypermusic-ai/dcn-js';
import { Wallet } from 'ethers';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Create an ephemeral account (or use your own private key)
const acct = Wallet.createRandom();

// Authenticate (nonce + ECDSA sign under the hood)
sdkClient.loginWithWallet(acct);

// Create a feature with dimensions & transformations, need to be logged first
sdkClient.featurePost({
  "name": "...",
  "dimensions": [
    {
      "feature_name": "...",
      "transformations": [
        {"name": "...", "args": [...]},
        ...
      ]
    },
    {"feature_name": "...", "transformations": [...]},
    ...
  ]
})

Transformations

A transformation is an executable operation. It specifies how to alter or reinterpret the space of a feature during execution. Transformations contains both metadata and the Solidity source that implements the operation. When executed, a transformation receives dimensional values as input and returns a new set of values according to its internal logic.

{
  "address": "0x...",
  "local_address": "0x...",
  "name": "...",
  "owner": "0x...",
  "sol_src": "..."
}

Get the latest version of a transformation.

GET /transformation/<transformationName>

Usage

curl -X GET "https://api.decentralised.art/transformation/<transformationName>"

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Get the latest version of a transformation
sdk_client.transformation_get("<transformationName>")

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Get the latest version of a transformation
sdkClient.transformationGet("<transformationName>");

Get a specific transformation version.

GET /transformation/<transformationName>/<transformationVersion>

Usage

curl -X GET "https://api.decentralised.art/transformation/<transformationName>/<transformationVersion>"

import dcn

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Get the specyfic version of a transformation
sdk_client.transformation_get("<transformationName>", "<transformationVersion>")

import { DcnClient } from '@hypermusic-ai/dcn-js';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Get the specyfic version of a transformation
sdkClient.transformationGet("<transformationName>", "<transformationVersion>");

Define/register a transformation by name and its Solidity source. Requires bearer token.

POST /transformation
        Authorization: Bearer <ACCESS_TOKEN>
        Content-Type: application/json
        {
            "name": "...",
            "sol_src": "..."
        }

Response

{
    "address": "0x...",
    "local_address": "0x...",
    "name": "...",
    "owner": "0x...",
    "sol_src": "..."
}

Usage

curl -X POST 
        -H "Authorization: Bearer <ACCESS_TOKEN>" 
        -H "Content-Type: application/json" 
        -d '{"name": "...", "sol_src": "..."}'
        "https://api.decentralised.art/transformation"

import dcn
from eth_account import Account

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Create an ephemeral account (or use your own private key)
acct = Account.create()

# Authenticate (nonce + ECDSA sign under the hood)
sdk_client.login_with_account(acct)

# Define/register a transformation by name and its Solidity source
sdk_client.transformation_post({
  "name": "...",
  "sol_src": "..."
})

import { DcnClient } from '@hypermusic-ai/dcn-js';
import { Wallet } from 'ethers';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Create an ephemeral account (or use your own private key)
const acct = Wallet.createRandom();

// Authenticate (nonce + ECDSA sign under the hood)
sdkClient.loginWithWallet(acct);

// Define/register a transformation by name and its Solidity source
sdkClient.transformationPost({
  "name": "...",
  "sol_src": "..."
});

Execution

Execution returns an array of data series.

[
    {
        "feature_path": "...",
        "data": [...]
    },
    ...
]

Execute a feature without running instances.

GET /execute/<featureName>/<numSamples>

Usage

curl -X GET
        -H "Authorization: Bearer <ACCESS_TOKEN>"
        "https://api.decentralised.art/execute/<featureName>/<numSamples>"

import dcn
from eth_account import Account

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Create an ephemeral account (or use your own private key)
acct = Account.create()

# Authenticate (nonce + ECDSA sign under the hood)
sdk_client.login_with_account(acct)

# Execute a feature without running instances
exec = sdk_client.execute("<featureName>", "<numSamples>")

import { DcnClient } from '@hypermusic-ai/dcn-js';
import { Wallet } from 'ethers';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Create an ephemeral account (or use your own private key)
const acct = Wallet.createRandom();

// Authenticate (nonce + ECDSA sign under the hood)
sdkClient.loginWithWallet(acct);

// Execute a feature without running instances
const exec = sdkClient.execute("<featureName>", "<numSamples>");

Execute a feature taking into account running instances.

GET /execute/<featureName>/<numSamples>/<runningInstances>

runningInstances is an inline-encoded list of tuples: [(startPoint;transformationShift), ...]

Usage

curl -X GET
        -H "Authorization: Bearer <ACCESS_TOKEN>"
        "https://api.decentralised.art/execute/<featureName>/<numSamples>/<runningInstances>"

import dcn
from eth_account import Account

# Client points to the public DCN API by default:
# https://api.decentralised.art
sdk_client = dcn.Client()

# Create an ephemeral account (or use your own private key)
acct = Account.create()

# Authenticate (nonce + ECDSA sign under the hood)
sdk_client.login_with_account(acct)

# Execute a feature with running instances
exec = sdk_client.execute("<featureName>", "<numSamples>", "<runningInstances>")

import { DcnClient } from '@hypermusic-ai/dcn-js';
import { Wallet } from 'ethers';

// Client points to the public DCN API by default:
// https://api.decentralised.art
const sdkClient = new DcnClient();

// Create an ephemeral account (or use your own private key)
const acct = Wallet.createRandom();

// Authenticate (nonce + ECDSA sign under the hood)
sdkClient.loginWithWallet(acct);

// Execute a feature with running instances
const exec = sdkClient.execute("<featureName>", "<numSamples>", "<runningInstances>");

Roadmap

To see the full roadmap, visit Roadmap & Planned Features

Planned feature

On-chain publication of features & transformations

Mainnet

We are designing a POST /publish endpoint for the DCN API that will allow feature and transformation definitions to be published to a blockchain mainnet.

This will enable verifiable provenance and on-chain references for DCN artifacts, so that compositional structures defined via /feature and /transformation can be anchored in a public ledger.

Exact endpoint shapes and schemas are still under active design and subject to change.

Note: this capability is not yet available in the public API surface.

Planned feature

Conditions: execution constraints for features

Protocol

We would like to introduce a dedicated Condition structure used in conjunction with features to control when and under which constraints a given feature can execute.

Conditions will allow you to bind execution to predicates such as caller address, time windows, feature dependencies or external state, and reference them from feature definitions.

Planned API additions include condition definition and reuse (e.g. named reusable conditions attached to multiple features), as well as validation of execution requests against the configured condition set. Exact data model and endpoints are still being iterated on.

Note: this capability is not yet available in the public API surface.