Skip to main content
API docs by Redocly

Neo Platform Inference API (1.0)

Download OpenAPI specification:Download

Public REST API for the NeoSpace platform (inference, chat, and platform management).

admin

List audits (org-wide)

List audit logs across all spaces. space_id is an optional filter from the query string.

query Parameters
limit
integer

Limit

after
string

After

action
Array of strings

Action

resource_type
Array of strings

Resource type

resource_id
Array of strings

Resource ID

space_id
Array of strings

Space ID (optional filter)

status_code
Array of integers

Status code

start_time
string

Start time (RFC3339 or YYYY-MM-DD)

end_time
string

End time (RFC3339 or YYYY-MM-DD)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/admin/audits" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Audit filter facets (org-wide)

Distinct values available for each audit filter, across every space.

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/admin/audits/facets" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "resource_types": [
    ]
}

Get audit by ID (org-wide)

Get any audit log entry regardless of space.

path Parameters
id
required
string

Audit ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/admin/audits/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "action": "example",
  • "api_key": "REDACTED",
  • "id": "aud_1a2b3c4d5e6f708192a3b4c5",
  • "is_api_key": false,
  • "metadata": { },
  • "resource_id": "aud_1a2b3c4d5e6f708192a3b4c5",
  • "resource_type": "example",
  • "space_id": "spa_1a2b3c4d5e6f708192a3b4c5",
  • "status_code": 1,
  • "timestamp": "2026-01-15T10:30:00Z",
  • "user_email": "someone@example.com",
  • "user_id": "usr_1a2b3c4d5e6f708192a3b4c5",
  • "user_name": "churn-propensity-v3"
}

metrics

Scrape the platform's metrics

Current value of every series the platform publishes, in Prometheus exposition format. This is the pull surface for an external collector — an OpenTelemetry Collector's prometheus receiver, vmagent, or Prometheus itself — and takes no parameters: the metric families are fixed (node_*, task_*, app_*, scalinggroup_*). Unlike /v1/metrics/query it needs no PromQL.

Authorizations:
ApiKeyAuth
header Parameters
Authorization
required
string
Default: Bearer <Add access token here>

Insert your access token

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/metrics" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
No sample

List label names

Label names known to the metrics backend, optionally restricted by a series selector.

Authorizations:
ApiKeyAuth
query Parameters
match
string

Series selector (singular, no brackets)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/metrics/labels" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "isPartial": false,
  • "status": "PENDING",
  • "warnings": [
    ]
}

List the values of one label

Values of a single label, optionally restricted by a series selector.

Authorizations:
ApiKeyAuth
path Parameters
label
required
string

Label name

query Parameters
match
string

Series selector (singular, no brackets)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/metrics/labels/{label}/values" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "isPartial": false,
  • "status": "PENDING",
  • "warnings": [
    ]
}

Instant query

Prometheus instant query against the platform's metrics backend: evaluates a PromQL expression at a single instant and returns one sample per matching series. GET /v1/metrics/query_range takes the same expressions and returns a time series per match instead. The query parameter lists the metric families, series and labels available.

Examples

  • avg(node_gpu_utilization) — average GPU utilization across all nodes.
  • 100 * node_gpu_memory_used_gb / clamp_min(node_gpu_memory_total_gb, 1) — VRAM in use per GPU, in %.
  • sum by (node) (node_gpu_power_watts) — power draw per node, in W.
  • node_gpu_health > 0 — GPUs currently in warn or fail.
  • sum by (node, iface) (rate(node_net_rx_bytes[5m])) — receive throughput per interface, in bytes/s.
  • topk(5, avg by (job) (task_gpu_utilization)) — the five jobs using the most GPU.
  • increase(task_oom_kill_total{job="my-job"}[1h]) — OOM kills per task of a job in the last hour.
  • sum(app_vllm:num_requests_waiting{job=~"my-group-[0-9]+"}) — requests queued across a scaling group's replicas.
  • scalinggroup_desired_replicas - scalinggroup_ready_replicas — replicas each scaling group is still waiting on.

Good to know

  • Counters (*_total, the network, NVLink and data-volume byte counts, task_cpu_usage_usec) only grow: wrap them in rate() or increase().
  • Nodes report about every 10 s and tasks every 15 s, so give rate() a window of at least 1m.
  • Keep backslashes out of the expression: the request fails with 502 on its way to the backend. Write [0-9] instead of \d and [.] instead of \..
Authorizations:
ApiKeyAuth
query Parameters
query
required
string

PromQL expression over the four metric families the platform publishes — the same set GET /v1/metrics exports. The series carry no cluster, tenant or space label. To list the metric names present right now, call GET /v1/metrics/labels/__name__/values.

node_* — each worker node's hardware. Every series carries node. *_gb values are GiB and *_percent values are 0–100.

  • CPU: node_cpu_usage_percent, node_cpu_cores, node_cpu_load1, node_cpu_load5, node_cpu_load15.
  • Memory: node_ram_total_gb, node_ram_used_gb, node_ram_used_percent, node_swap_used_gb, node_swap_percent.
  • Disk (adds device, mountpoint): node_disk_used_percent. node_disk_read_bytes_sec and node_disk_write_bytes_sec are published but not collected yet, and always read 0.
  • Network interface (adds iface, mac): node_net_speed_gbps, node_net_is_rdma (0/1), and the counters node_net_rx_bytes, node_net_tx_bytes, node_net_rx_errors, node_net_tx_errors. mac is absent on interfaces that have none, such as wg0. node_has_rdma (0/1, node level) says whether the node has any RDMA interface.
  • GPU usage (adds gpu_index, gpu_uuid): node_gpu_utilization (%), node_gpu_memory_used_gb, node_gpu_memory_total_gb, node_gpu_temperature_c, node_gpu_power_watts, node_gpu_power_limit_watts, node_gpu_sm_clock (MHz), node_gpu_fan_speed_percent.
  • GPU health (same labels): node_gpu_health (0 ok, 1 warn, 2 fail); ECC error counts node_gpu_ecc_sbe_volatile, node_gpu_ecc_dbe_volatile (since the last GPU reset), node_gpu_ecc_sbe_agg_total, node_gpu_ecc_dbe_agg_total (lifetime); retired pages node_gpu_retired_pages_sbe, node_gpu_retired_pages_dbe, node_gpu_retired_pages_pending (0/1); row remapping node_gpu_remap_correctable_rows, node_gpu_remap_uncorrectable_rows, node_gpu_remap_pending (0/1, needs a GPU reset), node_gpu_remap_failure (0/1), node_gpu_row_remap_banks_none, node_gpu_row_remap_banks_low; node_gpu_pcie_replay_count; node_gpu_xid_error (an Xid error code, not a count — present only when non-zero); node_gpu_nvlink_total_links, node_gpu_nvlink_inactive_links, node_gpu_fabric_health_mask.
  • NVLink, per link (adds gpu_index, link): node_nvlink_up (0/1) and the counters node_nvlink_tx_bytes, node_nvlink_rx_bytes, node_nvlink_replay_errors, node_nvlink_crc_errors. The node-level node_nvlink_total_links and node_nvlink_up_links always read 0 — use count by (node) (node_nvlink_up) and sum by (node) (node_nvlink_up) instead.
  • IMEX: node_imex_available (0/1, adds domain_state), only on nodes that report IMEX.
  • Data-volume mounts (adds source_node, proto, mount): the counters node_datavolume_bytes_read_total, node_datavolume_bytes_written_total, node_datavolume_read_ops_total, node_datavolume_write_ops_total, and node_datavolume_refcount. node_datavolume_dv_active is always 1 and adds dv_name: join on (node, mount) to attribute a mount's traffic to a data volume.

task_* — per-task container accounting. Labels: task; job and node when known; replica on every replica except replica 0; is_leader="true" on the leader only.

  • CPU: task_cpu_usage_percent (percent of one core, capped at 100 — for multi-core tasks use rate(task_cpu_usage_usec[5m]) / 1e6, in cores) and the counter task_cpu_usage_usec (µs).
  • Memory: task_memory_current_bytes, task_memory_peak_bytes, task_memory_limit_bytes, task_memory_usage_percent and task_memory_peak_percent (of the limit; 0 when the task has none), and the counters task_oom_kill_total, task_oom_event_total.
  • Network: the counters task_network_rx_bytes, task_network_tx_bytes, task_network_rx_errors, task_network_tx_errors.
  • GPU (adds gpu_index, the position among the task's own GPUs, not the node's index): task_gpu_utilization (%), task_gpu_memory_used_gb. Both read the whole GPU, not only the task's processes.

app_* — what a workload exports on its own metrics endpoint. The name is app_ plus the workload's metric name, with any character outside [A-Za-z0-9_:] replaced by _: vLLM's vllm:num_requests_running is queried as app_vllm:num_requests_running, and the bare name returns nothing. The set depends on the workload and its configuration — the app_vllm:spec_decode_* series, for instance, exist only with speculative decoding. To list what one job exports, call GET /v1/metrics/labels/__name__/values?match={job="<job>"}. Read them with these rules:

  • The series carry the task labels above and none of the workload's own. A metric whose meaning lives in its labels keeps one arbitrary label set, so breakdowns such as app_vllm:request_success_total (per finish reason), app_vllm:num_requests_waiting_by_reason, app_vllm:prompt_tokens_by_source_total, app_vllm:spec_decode_num_accepted_tokens_per_pos_total, app_http_requests_total and app_python_gc_* do not add up to their total, and *_info series always read 1.
  • A histogram is usable through _sum and _count only — rate(x_sum[5m]) / rate(x_count[5m]) is its mean. _bucket holds only the last bucket, equal to _count, so histogram_quantile does not apply.
  • *_created series are the client library's creation timestamps (unix seconds), not measurements.
  • A metric the workload stops exporting keeps being reported with its last value.

The platform's own workloads publish, among others:

  • LLM endpoints (vLLM). Gauges: app_vllm:num_requests_running, app_vllm:num_requests_waiting, app_vllm:kv_cache_usage_perc (0–1). Counters: app_vllm:prompt_tokens_total, app_vllm:generation_tokens_total, app_vllm:prompt_tokens_cached_total, app_vllm:num_preemptions_total, app_vllm:prefix_cache_queries_total, app_vllm:prefix_cache_hits_total, app_vllm:external_prefix_cache_queries_total, app_vllm:external_prefix_cache_hits_total, app_vllm:mm_cache_queries_total, app_vllm:mm_cache_hits_total, app_vllm:spec_decode_num_drafts_total, app_vllm:spec_decode_num_draft_tokens_total, app_vllm:spec_decode_num_accepted_tokens_total, app_vllm:estimated_flops_per_gpu_total, app_vllm:estimated_read_bytes_per_gpu_total, app_vllm:estimated_write_bytes_per_gpu_total. Latency histograms: app_vllm:e2e_request_latency_seconds, app_vllm:time_to_first_token_seconds, app_vllm:inter_token_latency_seconds, app_vllm:request_time_per_output_token_seconds, app_vllm:request_queue_time_seconds, app_vllm:request_prefill_time_seconds, app_vllm:request_decode_time_seconds, app_vllm:request_inference_time_seconds. Request-size histograms: app_vllm:request_prompt_tokens, app_vllm:request_generation_tokens, app_vllm:request_max_num_generation_tokens, app_vllm:request_params_n, app_vllm:request_params_max_tokens, app_vllm:request_prefill_kv_computed_tokens, app_vllm:request_num_preemptions, app_vllm:iteration_tokens_total. The server process also exports app_process_cpu_seconds_total, app_process_resident_memory_bytes, app_process_virtual_memory_bytes, app_process_open_fds, app_process_max_fds, app_process_start_time_seconds; of its app_http_* series only the unlabeled histogram app_http_request_duration_highr_seconds is reliable.
  • Inference servers (cortex), server role: app_cortex_server_up, app_cortex_server_concurrency, app_cortex_server_infer_requests_total, app_cortex_server_infer_errors_total, app_cortex_server_infer_inflight, app_cortex_server_infer_latency_p50_ms, app_cortex_server_infer_latency_p95_ms, app_cortex_server_infer_latency_p99_ms, and the same six for embeddings: app_cortex_server_embedding_requests_total, app_cortex_server_embedding_errors_total, app_cortex_server_embedding_inflight, app_cortex_server_embedding_latency_p50_ms, app_cortex_server_embedding_latency_p95_ms, app_cortex_server_embedding_latency_p99_ms.
  • Inference servers (cortex), engine roles: app_cortex_engine_up, app_cortex_engine_health_state, app_cortex_engine_request_total, app_cortex_engine_rejected_total, app_cortex_engine_inflight, app_cortex_engine_queue_depth, app_cortex_engine_max_batch, app_cortex_engine_forward_tokens_total, app_cortex_engine_pretokenized_total, app_cortex_engine_pretokenize_raw_total, app_cortex_engine_processes, app_cortex_engine_workers_alive, app_cortex_engine_resident_bytes, app_cortex_engine_worker_alive, app_cortex_engine_worker_forwards_total, app_cortex_engine_worker_last_forward_ms.

scalinggroup_* — the autoscaler's view of each scaling group, one sample per group every 15 s. Label: scaling_group. Series: scalinggroup_desired_replicas, scalinggroup_current_replicas, scalinggroup_ready_replicas, scalinggroup_observed_metric (the signal the scaling decision is taken on), scalinggroup_metric_target (only when the group scales toward a target value), scalinggroup_lb_active_backends. A group's replicas run as jobs named <scaling_group>-<index>, so their task_* and app_* series are selected with job=~"<scaling_group>-[0-9]+".

time
string

Evaluation instant, in integer unix seconds; defaults to now.

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/metrics/query?query=QUERY" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": {
    },
  • "isPartial": false,
  • "status": "PENDING",
  • "warnings": [
    ]
}

Range query

Prometheus range query against the platform's metrics backend: evaluates a PromQL expression over a window and returns one time series per match. start/end/step are optional and default to the last hour at a 30s step.

It takes the same expressions as GET /v1/metrics/query: the query parameter lists the metric families, series and labels available, and that operation has examples and the caveats both share.

Authorizations:
ApiKeyAuth
query Parameters
end
string

Range end, in integer unix seconds; defaults to now.

query
required
string

PromQL expression over the four metric families the platform publishes — the same set GET /v1/metrics exports. The series carry no cluster, tenant or space label. To list the metric names present right now, call GET /v1/metrics/labels/__name__/values.

node_* — each worker node's hardware. Every series carries node. *_gb values are GiB and *_percent values are 0–100.

  • CPU: node_cpu_usage_percent, node_cpu_cores, node_cpu_load1, node_cpu_load5, node_cpu_load15.
  • Memory: node_ram_total_gb, node_ram_used_gb, node_ram_used_percent, node_swap_used_gb, node_swap_percent.
  • Disk (adds device, mountpoint): node_disk_used_percent. node_disk_read_bytes_sec and node_disk_write_bytes_sec are published but not collected yet, and always read 0.
  • Network interface (adds iface, mac): node_net_speed_gbps, node_net_is_rdma (0/1), and the counters node_net_rx_bytes, node_net_tx_bytes, node_net_rx_errors, node_net_tx_errors. mac is absent on interfaces that have none, such as wg0. node_has_rdma (0/1, node level) says whether the node has any RDMA interface.
  • GPU usage (adds gpu_index, gpu_uuid): node_gpu_utilization (%), node_gpu_memory_used_gb, node_gpu_memory_total_gb, node_gpu_temperature_c, node_gpu_power_watts, node_gpu_power_limit_watts, node_gpu_sm_clock (MHz), node_gpu_fan_speed_percent.
  • GPU health (same labels): node_gpu_health (0 ok, 1 warn, 2 fail); ECC error counts node_gpu_ecc_sbe_volatile, node_gpu_ecc_dbe_volatile (since the last GPU reset), node_gpu_ecc_sbe_agg_total, node_gpu_ecc_dbe_agg_total (lifetime); retired pages node_gpu_retired_pages_sbe, node_gpu_retired_pages_dbe, node_gpu_retired_pages_pending (0/1); row remapping node_gpu_remap_correctable_rows, node_gpu_remap_uncorrectable_rows, node_gpu_remap_pending (0/1, needs a GPU reset), node_gpu_remap_failure (0/1), node_gpu_row_remap_banks_none, node_gpu_row_remap_banks_low; node_gpu_pcie_replay_count; node_gpu_xid_error (an Xid error code, not a count — present only when non-zero); node_gpu_nvlink_total_links, node_gpu_nvlink_inactive_links, node_gpu_fabric_health_mask.
  • NVLink, per link (adds gpu_index, link): node_nvlink_up (0/1) and the counters node_nvlink_tx_bytes, node_nvlink_rx_bytes, node_nvlink_replay_errors, node_nvlink_crc_errors. The node-level node_nvlink_total_links and node_nvlink_up_links always read 0 — use count by (node) (node_nvlink_up) and sum by (node) (node_nvlink_up) instead.
  • IMEX: node_imex_available (0/1, adds domain_state), only on nodes that report IMEX.
  • Data-volume mounts (adds source_node, proto, mount): the counters node_datavolume_bytes_read_total, node_datavolume_bytes_written_total, node_datavolume_read_ops_total, node_datavolume_write_ops_total, and node_datavolume_refcount. node_datavolume_dv_active is always 1 and adds dv_name: join on (node, mount) to attribute a mount's traffic to a data volume.

task_* — per-task container accounting. Labels: task; job and node when known; replica on every replica except replica 0; is_leader="true" on the leader only.

  • CPU: task_cpu_usage_percent (percent of one core, capped at 100 — for multi-core tasks use rate(task_cpu_usage_usec[5m]) / 1e6, in cores) and the counter task_cpu_usage_usec (µs).
  • Memory: task_memory_current_bytes, task_memory_peak_bytes, task_memory_limit_bytes, task_memory_usage_percent and task_memory_peak_percent (of the limit; 0 when the task has none), and the counters task_oom_kill_total, task_oom_event_total.
  • Network: the counters task_network_rx_bytes, task_network_tx_bytes, task_network_rx_errors, task_network_tx_errors.
  • GPU (adds gpu_index, the position among the task's own GPUs, not the node's index): task_gpu_utilization (%), task_gpu_memory_used_gb. Both read the whole GPU, not only the task's processes.

app_* — what a workload exports on its own metrics endpoint. The name is app_ plus the workload's metric name, with any character outside [A-Za-z0-9_:] replaced by _: vLLM's vllm:num_requests_running is queried as app_vllm:num_requests_running, and the bare name returns nothing. The set depends on the workload and its configuration — the app_vllm:spec_decode_* series, for instance, exist only with speculative decoding. To list what one job exports, call GET /v1/metrics/labels/__name__/values?match={job="<job>"}. Read them with these rules:

  • The series carry the task labels above and none of the workload's own. A metric whose meaning lives in its labels keeps one arbitrary label set, so breakdowns such as app_vllm:request_success_total (per finish reason), app_vllm:num_requests_waiting_by_reason, app_vllm:prompt_tokens_by_source_total, app_vllm:spec_decode_num_accepted_tokens_per_pos_total, app_http_requests_total and app_python_gc_* do not add up to their total, and *_info series always read 1.
  • A histogram is usable through _sum and _count only — rate(x_sum[5m]) / rate(x_count[5m]) is its mean. _bucket holds only the last bucket, equal to _count, so histogram_quantile does not apply.
  • *_created series are the client library's creation timestamps (unix seconds), not measurements.
  • A metric the workload stops exporting keeps being reported with its last value.

The platform's own workloads publish, among others:

  • LLM endpoints (vLLM). Gauges: app_vllm:num_requests_running, app_vllm:num_requests_waiting, app_vllm:kv_cache_usage_perc (0–1). Counters: app_vllm:prompt_tokens_total, app_vllm:generation_tokens_total, app_vllm:prompt_tokens_cached_total, app_vllm:num_preemptions_total, app_vllm:prefix_cache_queries_total, app_vllm:prefix_cache_hits_total, app_vllm:external_prefix_cache_queries_total, app_vllm:external_prefix_cache_hits_total, app_vllm:mm_cache_queries_total, app_vllm:mm_cache_hits_total, app_vllm:spec_decode_num_drafts_total, app_vllm:spec_decode_num_draft_tokens_total, app_vllm:spec_decode_num_accepted_tokens_total, app_vllm:estimated_flops_per_gpu_total, app_vllm:estimated_read_bytes_per_gpu_total, app_vllm:estimated_write_bytes_per_gpu_total. Latency histograms: app_vllm:e2e_request_latency_seconds, app_vllm:time_to_first_token_seconds, app_vllm:inter_token_latency_seconds, app_vllm:request_time_per_output_token_seconds, app_vllm:request_queue_time_seconds, app_vllm:request_prefill_time_seconds, app_vllm:request_decode_time_seconds, app_vllm:request_inference_time_seconds. Request-size histograms: app_vllm:request_prompt_tokens, app_vllm:request_generation_tokens, app_vllm:request_max_num_generation_tokens, app_vllm:request_params_n, app_vllm:request_params_max_tokens, app_vllm:request_prefill_kv_computed_tokens, app_vllm:request_num_preemptions, app_vllm:iteration_tokens_total. The server process also exports app_process_cpu_seconds_total, app_process_resident_memory_bytes, app_process_virtual_memory_bytes, app_process_open_fds, app_process_max_fds, app_process_start_time_seconds; of its app_http_* series only the unlabeled histogram app_http_request_duration_highr_seconds is reliable.
  • Inference servers (cortex), server role: app_cortex_server_up, app_cortex_server_concurrency, app_cortex_server_infer_requests_total, app_cortex_server_infer_errors_total, app_cortex_server_infer_inflight, app_cortex_server_infer_latency_p50_ms, app_cortex_server_infer_latency_p95_ms, app_cortex_server_infer_latency_p99_ms, and the same six for embeddings: app_cortex_server_embedding_requests_total, app_cortex_server_embedding_errors_total, app_cortex_server_embedding_inflight, app_cortex_server_embedding_latency_p50_ms, app_cortex_server_embedding_latency_p95_ms, app_cortex_server_embedding_latency_p99_ms.
  • Inference servers (cortex), engine roles: app_cortex_engine_up, app_cortex_engine_health_state, app_cortex_engine_request_total, app_cortex_engine_rejected_total, app_cortex_engine_inflight, app_cortex_engine_queue_depth, app_cortex_engine_max_batch, app_cortex_engine_forward_tokens_total, app_cortex_engine_pretokenized_total, app_cortex_engine_pretokenize_raw_total, app_cortex_engine_processes, app_cortex_engine_workers_alive, app_cortex_engine_resident_bytes, app_cortex_engine_worker_alive, app_cortex_engine_worker_forwards_total, app_cortex_engine_worker_last_forward_ms.

scalinggroup_* — the autoscaler's view of each scaling group, one sample per group every 15 s. Label: scaling_group. Series: scalinggroup_desired_replicas, scalinggroup_current_replicas, scalinggroup_ready_replicas, scalinggroup_observed_metric (the signal the scaling decision is taken on), scalinggroup_metric_target (only when the group scales toward a target value), scalinggroup_lb_active_backends. A group's replicas run as jobs named <scaling_group>-<index>, so their task_* and app_* series are selected with job=~"<scaling_group>-[0-9]+".

start
string

Range start, in integer unix seconds; defaults to one hour before end.

step
string

Resolution, as a duration (30s, 5m) or integer seconds; defaults to 30s.

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/metrics/query_range?query=QUERY" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": {
    },
  • "isPartial": false,
  • "status": "PENDING",
  • "warnings": [
    ]
}

seats

Get all seats

Lists seats on whichever axis owns them. While a provider is SCIM-governed the IdP owns which seats exist, so the rows are directory groups carrying seat_id (nil when the group has no permission binding yet), after is a numeric offset, and unmapped_seats reports local rows the directory does not know. Otherwise the rows are seats and after is a seat id. scim_governed says which.

query Parameters
limit
integer
Default: 10

limit

after
string

Cursor: a seat id, or a numeric offset while SCIM-governed

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/seats" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false,
  • "scim_governed": false,
  • "unmapped_seats": [
    ]
}

Create seat

Create a new seat

Request Body schema: application/json
required

Seat creation request

object

Grant is the authorization, with the two axes stated separately. Optional at creation: the UI creates a bare seat and configures the grant afterwards via the seat editor.

group_id
string
name
string

Name asks the platform to create the group and own its name. GroupID binds to a group the identity provider already provisioned. Exactly one is given: which one decides who owns the group, so they cannot be merged.

permissions
Array of strings (permissions.Permission)
Items Enum: "audits:get" "audits:list" "api-keys:create" "api-keys:delete" "api-keys:get" "api-keys:list" "api-keys:update" "architectures:list" "benchmarks:create" "benchmarks:delete" "benchmarks:get" "benchmarks:list" "benchmarks:update" "checkpoints:list" "checkpoints:update" "clusters:create" "clusters:delete" "clusters:get-stats" "clusters:list" "connectors:create" "connectors:files:compare" "connectors:delete" "connectors:files" "connectors:get" "connectors:list" "data-models:create" "data-models:delete" "data-models:get" "data-models:list" "data-models:update" "data-enhancements:create" "data-enhancements:delete" "data-enhancements:get" "data-enhancements:list" "data-enhancements:update" "data-profiles:create" "data-profiles:archive" "data-profiles:delete" "data-profiles:get" "data-profiles:stats" "data-profiles:list" "data-profiles:update" "drift-policies:create" "drift-policies:delete" "drift-policies:get" "drift-policies:list" "drift-policies:update" "favorites:create" "favorites:delete" "folders:create" "folders:delete" "folders:get" "folders:list" "folders:move" "folders:update" "data-preprocesses:create" "data-preprocesses:archive" "data-preprocesses:delete" "data-preprocesses:get" "data-preprocesses:columns" "data-preprocesses:list" "data-preprocesses:update" "data-extractions:create" "data-extractions:delete" "data-extractions:get" "data-extractions:list" "data-extractions:update" "model-designs:create" "model-designs:get" "model-designs:list" "model-designs:update" "model-designs:publish" "model-designs:archive" "model-designs:delete" "evaluations:create" "inference-servers:create" "inference-servers:delete" "inference-servers:get" "inference-servers:list" "inference-servers:update" "served-models:list" "served-models:create" "model-endpoints:create" "model-endpoints:get" "model-endpoints:list" "model-endpoints:delete" "leaderboards:list" "neocore:read" "neocore:write" "metrics:read" "spaces:create" "spaces:delete" "spaces:get" "spaces:list" "spaces:get-members" "spaces:invite" "spaces:assign-cluster" "spaces:update" "trainings:create" "trainings:cancel" "trainings:delete" "trainings:get" "trainings:get-metrics" "trainings:get-logs" "trainings:list" "trainings:update" "seats:create" "seats:delete" "seats:get" "seats:list" "seats:update" "admin:users:list" "admin:users:update" "admin:users:delete" "admin:oidc:manage" "admin:audits:list" "admin:audits:get" "admin:metrics:read" "admin:mfa-policy:get" "admin:mfa-policy:update" "notifications:list" "notifications:update" "nodes:list" "nodes:create" "nodes:delete" "nodes:update" "nodes:move" "nodes:token:generate" "external-secrets:create" "external-secrets:delete" "external-secrets:get" "external-secrets:list" "external-secrets:resync" "*"

Deprecated: use Grant.

spaces
Array of strings

Spaces and Permissions are the deprecated flat pair, kept for clients that have not moved to Grant. Sending both shapes in one request is a 400 — there is no sane way to merge two statements of the same thing.

Deprecated: use Grant.

Responses

Request samples

Content type
application/json
{
  • "grant": {
    },
  • "group_id": "string",
  • "name": "string",
  • "permissions": [
    ],
  • "spaces": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "grant": {
    },
  • "id": "sea_1a2b3c4d5e6f708192a3b4c5",
  • "name": "Data scientist",
  • "permissions": [
    ],
  • "spaces": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z",
  • "updated_by": "example"
}

Delete seat

Delete a seat by ID

path Parameters
id
required
string

Seat ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/seats/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5"
}

Get seat

Retrieve a seat by ID

path Parameters
id
required
string

Seat ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/seats/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "grant": {
    },
  • "id": "sea_1a2b3c4d5e6f708192a3b4c5",
  • "name": "Data scientist",
  • "permissions": [
    ],
  • "spaces": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z",
  • "updated_by": "example"
}

Update seat

Update a seat by ID

path Parameters
id
required
string

Seat ID

Request Body schema: application/json
required

Seat update request

object

Grant replaces the seat's authorization wholesale when present, and leaves it untouched when absent. It is deliberately not merged field by field: the grant is one coherent statement, and merging halves of it against stored values is what made a coherent edit look incoherent — dropping the last space-scoped permission was judged against the Spaces it was replacing.

name
string
permissions
Array of strings (permissions.Permission)
Items Enum: "audits:get" "audits:list" "api-keys:create" "api-keys:delete" "api-keys:get" "api-keys:list" "api-keys:update" "architectures:list" "benchmarks:create" "benchmarks:delete" "benchmarks:get" "benchmarks:list" "benchmarks:update" "checkpoints:list" "checkpoints:update" "clusters:create" "clusters:delete" "clusters:get-stats" "clusters:list" "connectors:create" "connectors:files:compare" "connectors:delete" "connectors:files" "connectors:get" "connectors:list" "data-models:create" "data-models:delete" "data-models:get" "data-models:list" "data-models:update" "data-enhancements:create" "data-enhancements:delete" "data-enhancements:get" "data-enhancements:list" "data-enhancements:update" "data-profiles:create" "data-profiles:archive" "data-profiles:delete" "data-profiles:get" "data-profiles:stats" "data-profiles:list" "data-profiles:update" "drift-policies:create" "drift-policies:delete" "drift-policies:get" "drift-policies:list" "drift-policies:update" "favorites:create" "favorites:delete" "folders:create" "folders:delete" "folders:get" "folders:list" "folders:move" "folders:update" "data-preprocesses:create" "data-preprocesses:archive" "data-preprocesses:delete" "data-preprocesses:get" "data-preprocesses:columns" "data-preprocesses:list" "data-preprocesses:update" "data-extractions:create" "data-extractions:delete" "data-extractions:get" "data-extractions:list" "data-extractions:update" "model-designs:create" "model-designs:get" "model-designs:list" "model-designs:update" "model-designs:publish" "model-designs:archive" "model-designs:delete" "evaluations:create" "inference-servers:create" "inference-servers:delete" "inference-servers:get" "inference-servers:list" "inference-servers:update" "served-models:list" "served-models:create" "model-endpoints:create" "model-endpoints:get" "model-endpoints:list" "model-endpoints:delete" "leaderboards:list" "neocore:read" "neocore:write" "metrics:read" "spaces:create" "spaces:delete" "spaces:get" "spaces:list" "spaces:get-members" "spaces:invite" "spaces:assign-cluster" "spaces:update" "trainings:create" "trainings:cancel" "trainings:delete" "trainings:get" "trainings:get-metrics" "trainings:get-logs" "trainings:list" "trainings:update" "seats:create" "seats:delete" "seats:get" "seats:list" "seats:update" "admin:users:list" "admin:users:update" "admin:users:delete" "admin:oidc:manage" "admin:audits:list" "admin:audits:get" "admin:metrics:read" "admin:mfa-policy:get" "admin:mfa-policy:update" "notifications:list" "notifications:update" "nodes:list" "nodes:create" "nodes:delete" "nodes:update" "nodes:move" "nodes:token:generate" "external-secrets:create" "external-secrets:delete" "external-secrets:get" "external-secrets:list" "external-secrets:resync" "*"

Deprecated: use Grant. Merged against the stored grant, as before.

spaces
Array of strings

Deprecated: use Grant. Merged against the stored grant, as before.

Responses

Request samples

Content type
application/json
{
  • "grant": {
    },
  • "name": "string",
  • "permissions": [
    ],
  • "spaces": [
    ]
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "grant": {
    },
  • "id": "sea_1a2b3c4d5e6f708192a3b4c5",
  • "name": "Data scientist",
  • "permissions": [
    ],
  • "spaces": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z",
  • "updated_by": "example"
}

spaces

Get all spaces

Retrieve all spaces

query Parameters
limit
integer
Default: 10

Limit

after
string
Default: "\"\""

After

name
string

Filter by space name

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create space

Create a new space

Request Body schema: application/json
required

Space creation request

description
required
string
name
required
string
seat_id
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "seat_id": "string"
}

Response samples

Content type
application/json
{
  • "cluster_id": "clu_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "description": "Scores the active customer base every morning.",
  • "id": "spa_1a2b3c4d5e6f708192a3b4c5",
  • "name": "Risk",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "updated_by": "example"
}

Delete space

Delete a space by ID

path Parameters
spaceId
required
string

Space ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5"
}

Get space

Retrieve a space by ID

path Parameters
spaceId
required
string

Space ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "cluster_id": "clu_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "description": "Scores the active customer base every morning.",
  • "id": "spa_1a2b3c4d5e6f708192a3b4c5",
  • "name": "Risk",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "updated_by": "example"
}

Update space

Update a space by ID

path Parameters
spaceId
required
string

Space ID

Request Body schema: application/json
required

Space update request

description
string
name
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "cluster_id": "clu_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "description": "Scores the active customer base every morning.",
  • "id": "spa_1a2b3c4d5e6f708192a3b4c5",
  • "name": "Risk",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "updated_by": "example"
}

audits

List audits

List audits

query Parameters
limit
integer

Limit

after
string

After

action
string

Action

resource_type
string

Resource type

resource_id
string

Resource ID

user_id
string

User ID

user_email
string

User email

user_name
string

User name

space_id
string

Space ID

status_code
integer

Status code

start_time
string

Start time (RFC3339 format, e.g. 2024-01-15T10:00:00Z or date only 2024-01-15)

end_time
string

End time (RFC3339 format, e.g. 2024-01-15T18:00:00Z or date only 2024-01-15)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/audits" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Audit filter facets

The distinct action and resource_type values present in this space's audit log, so the activity-log filters are driven by the data rather than a hard-coded list.

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/audits/facets" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "actions": [
    ],
  • "resource_types": [
    ]
}

Get audit by ID

Get audit by ID with all details including metadata

path Parameters
id
required
string

Audit ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/audits/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "action": "example",
  • "api_key": "REDACTED",
  • "id": "aud_1a2b3c4d5e6f708192a3b4c5",
  • "is_api_key": false,
  • "metadata": { },
  • "resource_id": "aud_1a2b3c4d5e6f708192a3b4c5",
  • "resource_type": "example",
  • "space_id": "spa_1a2b3c4d5e6f708192a3b4c5",
  • "status_code": 1,
  • "timestamp": "2026-01-15T10:30:00Z",
  • "user_email": "someone@example.com",
  • "user_id": "usr_1a2b3c4d5e6f708192a3b4c5",
  • "user_name": "churn-propensity-v3"
}

batch-inference

Every batch inference run in the space

query Parameters
limit
integer
Default: 10

Page size

after
string

Cursor from the previous page

status
string

Comma-separated run statuses to keep

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/batch-inference-runs" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Start a batch run from a checkpoint, with nothing deployed

Request Body schema: application/json
required

Body (checkpoint_id required)

object

AnchorSource scores each client at the positions named by a dataset/file instead of at a single date (cortex dataset.anchor_datasets); mutually exclusive with flags.infer_target_date.

checkpoint_id
string

CheckpointID scores with a checkpoint directly — no inference server, nothing deployed. Ignored when the route already carries a server id.

event_dataset_ids
Array of strings

EventDatasetIDs are the registered datasets feeding the model input views. It may be empty when every view is instead fed by a local dataset below; full per-view coverage (registered OR local) is enforced in the service, so there is no min=1 binding here.

object

EventDatasetShifts optionally overrides the per-dataset temporal shift, keyed by the dataset id (registered) or the local dataset_key. Absent keys inherit the shift the dataset was trained with; a present key wins, and an explicit empty string clears it (score with no offset). Same string encoding as the training shift ("1h" or "|"). Omit entirely to reproduce training exactly.

Array of objects (request.CreateBatchInferenceLocalDataset)

EventDatasetsLocal are event datasets fed by absolute path or neocore DataVolume rather than a registered dataset id. Each covers the model input view named by its dataset_key, so a run can be driven entirely from local paths; a run with none stays byte-identical. Appended to the id-resolved event datasets.

object (request.CreateBatchInferenceFlagsBody)
inference_version
string <= 128 characters

InferenceVersion pins the TAG of the cortex-infer image this run uses (e.g. "v0.0.9"): the carrier init container injects that image's engines/ into the ranks, and the publish step runs its binary. Empty = the architecture's tag. It does NOT change the model image — the ranks run the cortex image the checkpoint was trained with, chosen by the checkpoint and never by an operator here.

object

Output optionally sets where this run's writer publishes predictions. ConnectorID set → an output connector (aws-s3 / aws-s3-instance-profile / oracle_s3 / oracle_instance_principal / local) at Path; empty ConnectorID + non-empty Path → a raw shared-filesystem path; both empty → the auto-derived run output dir (current behavior). Mirrors the deploy-time output-destination shape.

object

Parallelism fans the run out into N independent data shards (bucket-shard i/N), each a driver + its own output writer, mirroring the hand-run sharded batch. Nil or shards<=1 runs the single-driver path (byte-identical to before).

object (request.CreateBatchInferencePool)
recipe_yaml
string

RecipeYaml, when set, is a full user-edited cortex-batch-infer recipe document used as the run's recipe instead of the field-derived one — the advanced "YAML" mode. The field-derived recipe knobs are ignored (the YAML wins for non-managed keys), but the datasets/pool/output are still resolved the normal way to drive the job wiring (managed fields + volumes). The platform re-injects its managed fields over it at submit so the user can't break the wiring. Malformed YAML → 400. Empty = the field-derived recipe (byte-identical to the stepper path).

On a server-scoped run, a top-level driver: dataloader makes the document a cortex BENCHMARK recipe instead, run by cortex-infer's dataloader driver — benchmark.py with its forward on this server's engines, a validation run — as one gang job. The platform owns base_model_dir, output_dir and the transport addresses; nothing is published.

required
object (request.CreateBatchInferenceTimeRange)

Responses

Request samples

Content type
application/json
{
  • "anchor_source": {
    },
  • "checkpoint_id": "string",
  • "event_dataset_ids": [
    ],
  • "event_dataset_shifts": {
    },
  • "event_datasets_local": [
    ],
  • "flags": {
    },
  • "inference_version": "string",
  • "output": {
    },
  • "parallelism": {
    },
  • "pool": {
    },
  • "recipe_yaml": "string",
  • "time_range": {
    }
}

Response samples

Content type
application/json
{
  • "cache_dir": "/datasets/transactions",
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "event_dataset_ids": [
    ],
  • "finished_at": "2026-01-15T10:30:00Z",
  • "flags": {
    },
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "inference_version": "1.0.0",
  • "output_destination": {
    },
  • "output_dir": "/datasets/transactions",
  • "output_summary": {
    },
  • "pool": {
    },
  • "progress": {
    },
  • "publish": {
    },
  • "recipe_yaml": "example",
  • "shards": 1,
  • "space": "example",
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "time_range": {
    },
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Get a batch inference run

path Parameters
id
required
string

Batch inference run ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/batch-inference-runs/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "cache_dir": "/datasets/transactions",
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "event_dataset_ids": [
    ],
  • "finished_at": "2026-01-15T10:30:00Z",
  • "flags": {
    },
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "inference_version": "1.0.0",
  • "output_destination": {
    },
  • "output_dir": "/datasets/transactions",
  • "output_summary": {
    },
  • "pool": {
    },
  • "progress": {
    },
  • "publish": {
    },
  • "recipe_yaml": "example",
  • "shards": 1,
  • "space": "example",
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "time_range": {
    },
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Cancel a batch inference run

Stop a queued or running batch run. Output already written is kept.

path Parameters
id
required
string

Batch inference run ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/batch-inference-runs/{id}/cancel" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "cache_dir": "/datasets/transactions",
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "event_dataset_ids": [
    ],
  • "finished_at": "2026-01-15T10:30:00Z",
  • "flags": {
    },
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "inference_version": "1.0.0",
  • "output_destination": {
    },
  • "output_dir": "/datasets/transactions",
  • "output_summary": {
    },
  • "pool": {
    },
  • "progress": {
    },
  • "publish": {
    },
  • "recipe_yaml": "example",
  • "shards": 1,
  • "space": "example",
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "time_range": {
    },
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Batch run metrics

Throughput, shard progress and resource use for a run over a rolling window.

path Parameters
id
required
string

Batch inference run ID

query Parameters
window
string
Default: "10m"

Metrics window as a Go duration (e.g. 10m, 1h)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/batch-inference-runs/{id}/metrics" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "batch_p50_ms": [
    ],
  • "batch_p95_ms": [
    ],
  • "chunks_per_second": [
    ],
  • "inflight": [
    ],
  • "memory_rss_mb": [
    ],
  • "throughput": [
    ],
  • "users_per_second": [
    ],
  • "window": "example",
  • "writer_errors": [
    ],
  • "writer_rows": [
    ]
}

Per-shard breakdown of a batch run

Status, failure reason, nodes, live progress and writer status for each shard of a data-parallel run — on failure, which shard broke and why.

path Parameters
id
required
string

Batch inference run ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/batch-inference-runs/{id}/shards" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "shards": [
    ]
}

Datasets a checkpoint accepts for a batch run

path Parameters
id
required
string

Checkpoint ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/checkpoints/{id}/batch-model" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "info": {
    },
  • "input_views": [
    ],
  • "target_views": [
    ]
}

List a server's batch runs

path Parameters
id
required
string

Inference server ID

query Parameters
limit
integer
Default: 10

Page size

after
string

Cursor for pagination

status
string

Comma-separated status filter

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/batch-runs" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Start a batch run on an inference server

Score a population offline against the model this server serves.

path Parameters
id
required
string

Inference server ID

Request Body schema: application/json
required

Batch run configuration

object

AnchorSource scores each client at the positions named by a dataset/file instead of at a single date (cortex dataset.anchor_datasets); mutually exclusive with flags.infer_target_date.

checkpoint_id
string

CheckpointID scores with a checkpoint directly — no inference server, nothing deployed. Ignored when the route already carries a server id.

event_dataset_ids
Array of strings

EventDatasetIDs are the registered datasets feeding the model input views. It may be empty when every view is instead fed by a local dataset below; full per-view coverage (registered OR local) is enforced in the service, so there is no min=1 binding here.

object

EventDatasetShifts optionally overrides the per-dataset temporal shift, keyed by the dataset id (registered) or the local dataset_key. Absent keys inherit the shift the dataset was trained with; a present key wins, and an explicit empty string clears it (score with no offset). Same string encoding as the training shift ("1h" or "|"). Omit entirely to reproduce training exactly.

Array of objects (request.CreateBatchInferenceLocalDataset)

EventDatasetsLocal are event datasets fed by absolute path or neocore DataVolume rather than a registered dataset id. Each covers the model input view named by its dataset_key, so a run can be driven entirely from local paths; a run with none stays byte-identical. Appended to the id-resolved event datasets.

object (request.CreateBatchInferenceFlagsBody)
inference_version
string <= 128 characters

InferenceVersion pins the TAG of the cortex-infer image this run uses (e.g. "v0.0.9"): the carrier init container injects that image's engines/ into the ranks, and the publish step runs its binary. Empty = the architecture's tag. It does NOT change the model image — the ranks run the cortex image the checkpoint was trained with, chosen by the checkpoint and never by an operator here.

object

Output optionally sets where this run's writer publishes predictions. ConnectorID set → an output connector (aws-s3 / aws-s3-instance-profile / oracle_s3 / oracle_instance_principal / local) at Path; empty ConnectorID + non-empty Path → a raw shared-filesystem path; both empty → the auto-derived run output dir (current behavior). Mirrors the deploy-time output-destination shape.

object

Parallelism fans the run out into N independent data shards (bucket-shard i/N), each a driver + its own output writer, mirroring the hand-run sharded batch. Nil or shards<=1 runs the single-driver path (byte-identical to before).

object (request.CreateBatchInferencePool)
recipe_yaml
string

RecipeYaml, when set, is a full user-edited cortex-batch-infer recipe document used as the run's recipe instead of the field-derived one — the advanced "YAML" mode. The field-derived recipe knobs are ignored (the YAML wins for non-managed keys), but the datasets/pool/output are still resolved the normal way to drive the job wiring (managed fields + volumes). The platform re-injects its managed fields over it at submit so the user can't break the wiring. Malformed YAML → 400. Empty = the field-derived recipe (byte-identical to the stepper path).

On a server-scoped run, a top-level driver: dataloader makes the document a cortex BENCHMARK recipe instead, run by cortex-infer's dataloader driver — benchmark.py with its forward on this server's engines, a validation run — as one gang job. The platform owns base_model_dir, output_dir and the transport addresses; nothing is published.

required
object (request.CreateBatchInferenceTimeRange)

Responses

Request samples

Content type
application/json
{
  • "anchor_source": {
    },
  • "checkpoint_id": "string",
  • "event_dataset_ids": [
    ],
  • "event_dataset_shifts": {
    },
  • "event_datasets_local": [
    ],
  • "flags": {
    },
  • "inference_version": "string",
  • "output": {
    },
  • "parallelism": {
    },
  • "pool": {
    },
  • "recipe_yaml": "string",
  • "time_range": {
    }
}

Response samples

Content type
application/json
{
  • "cache_dir": "/datasets/transactions",
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "event_dataset_ids": [
    ],
  • "finished_at": "2026-01-15T10:30:00Z",
  • "flags": {
    },
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "inference_version": "1.0.0",
  • "output_destination": {
    },
  • "output_dir": "/datasets/transactions",
  • "output_summary": {
    },
  • "pool": {
    },
  • "progress": {
    },
  • "publish": {
    },
  • "recipe_yaml": "example",
  • "shards": 1,
  • "space": "example",
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "time_range": {
    },
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z"
}

checkpoints

List checkpoints

List checkpoints by ID

Authorizations:
ApiKeyAuth
query Parameters
limit
integer
Default: 10

Limit

after
string
Default: "\"\""

After

query
string

Case-insensitive substring match on checkpoint name

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/checkpoints" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Get checkpoint

Get a single checkpoint by id

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Checkpoint ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/checkpoints/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "epoch": 1,
  • "id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "metrics": { },
  • "name": "churn-propensity-v3-step-4000",
  • "path": "/datasets/transactions",
  • "step": 1,
  • "target_metrics": [
    ],
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "training_kind": "PRETRAIN",
  • "training_name": "churn-propensity-v3"
}

Rename checkpoint

Update the display name of a checkpoint

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Checkpoint ID

Request Body schema: application/json
required

Body

name
required
string [ 1 .. 128 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "epoch": 1,
  • "id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "metrics": { },
  • "name": "churn-propensity-v3-step-4000",
  • "path": "/datasets/transactions",
  • "step": 1,
  • "target_metrics": [
    ],
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "training_kind": "PRETRAIN",
  • "training_name": "churn-propensity-v3"
}

Inference deploy config for a checkpoint

Resolve the images + tunables an inference server built from this checkpoint would deploy with (checkpoint → training → architecture).

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Checkpoint ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/checkpoints/{id}/inference-config" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "image_go": "registry.example.com/image:tag",
  • "max_seqlen": 4,
  • "memory_margin": 0.5,
  • "node_fraction": 0.5,
  • "token_budget": 1
}

connectors

List connectors

Retrieve a list of connectors with pagination

Authorizations:
ApiKeyAuth
query Parameters
limit
integer
Default: 10

limit

after
string

after

name
string

case-insensitive regular expression matched against the connector name

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/connectors" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create connector

Create a new connector

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Connector creation request

external_secret_id
string
index_interval_seconds
integer >= 0

IndexIntervalSeconds: how often the catalog re-scans this connector for new/changed data; forwarded to the neocore datasource spec. Nil/0 disables automatic re-indexing. The UI defaults to 300 (5 min).

object (request.LocalConfig)
name
required
string
object (request.OracleDefaultConfigReq)
object (request.OracleInstancePrincipalConfig)
object (request.OracleS3Config)
object (request.S3Config)
object (request.S3InstanceProfileConfig)
type
required
string
Enum: "aws-s3" "aws-s3-instance-profile" "oracle_s3" "oracle_instance_principal" "oracle" "local"

Responses

Request samples

Content type
application/json
{
  • "external_secret_id": "string",
  • "index_interval_seconds": 0,
  • "local": {
    },
  • "name": "string",
  • "oracle": {
    },
  • "oracle_instance_principal": {
    },
  • "oracle_s3": {
    },
  • "s3": {
    },
  • "s3_instance_profile": {
    },
  • "type": "aws-s3"
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "endpoint": "https://example.com/path",
  • "external_secret_id": "sec_1a2b3c4d5e6f708192a3b4c5",
  • "extraction_id": "act_1a2b3c4d5e6f708192a3b4c5",
  • "id": "conn_1a2b3c4d5e6f708192a3b4c5",
  • "name": "warehouse-transactions",
  • "namespace": "Risk",
  • "paths": [
    ],
  • "prefix": "example",
  • "provider": "aws-s3",
  • "region": "example",
  • "volume_name": "shared-datasets",
  • "volume_root": "example"
}

Compare connector files

Compare connector files by ID

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

Compare connector files request

required
Array of objects (request.CompareConnector)
Array
files
Array of strings
id
string

Responses

Request samples

Content type
application/json
{
  • "compare": [
    ]
}

Response samples

Content type
application/json
{
  • "schema_groups": [
    ]
}

Delete connector

Delete a connector by ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Connector ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/connectors/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5"
}

Get connector

Retrieve a connector by ID

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Connector ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/connectors/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "endpoint": "https://example.com/path",
  • "external_secret_id": "sec_1a2b3c4d5e6f708192a3b4c5",
  • "extraction_id": "act_1a2b3c4d5e6f708192a3b4c5",
  • "id": "conn_1a2b3c4d5e6f708192a3b4c5",
  • "name": "warehouse-transactions",
  • "namespace": "Risk",
  • "paths": [
    ],
  • "prefix": "example",
  • "provider": "aws-s3",
  • "region": "example",
  • "volume_name": "shared-datasets",
  • "volume_root": "example"
}

List files in a connector (S3)

List files for a connector by ID (currently supports S3 connectors)

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Connector ID

query Parameters
prefix
string

File prefix filter

limit
integer

Maximum number of files to return

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/connectors/{id}/files" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
[
  • [
    ]
]

Get connector live status

Returns the live status (latest/active runs, schema count) for a connector by proxying neocore.

Authorizations:
ApiKeyAuth
path Parameters
id
required
string

Connector ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/connectors/{id}/status" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "active_index_run": {
    },
  • "active_parquet_scan": {
    },
  • "index_status": "PENDING",
  • "is_indexing": false,
  • "is_profiling": false,
  • "latest_index_run": {
    },
  • "latest_parquet_scan": {
    },
  • "profile_status": "PENDING",
  • "schema_count": 8
}

data-enhancements

List data enhancements

Paginated list of data enhancement workspaces in the current space

query Parameters
limit
integer
Default: 10

Page size

after
string

Cursor

name
string

Filter by name (substring)

status
string

Filter by status

header Parameters
Space
required
string

Space ID (spa_*)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-enhancements" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create data enhancement workspace

Create a new data enhancement workspace scoped to the Space header (source datasets, status, audit). Requires JWT or API key and data-enhancements:create.

header Parameters
Space
required
string

Space ID (spa_*)

Request Body schema: application/json
required

Create request

description
string
name
required
string
raw_dataset_ids
Array of strings
status
string
Enum: "DRAFT" "PROCESSING" "READY" "FAILED"

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "raw_dataset_ids": [
    ],
  • "status": "DRAFT"
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "description": "Scores the active customer base every morning.",
  • "facts_count": 8,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "last_updated": "example",
  • "name": "churn-propensity-v3",
  • "predictions_count": 8,
  • "raw_dataset_ids": [
    ],
  • "status": "DRAFT",
  • "transformations_count": 8
}

Delete data enhancement

Delete a data enhancement workspace by ID in the current space

path Parameters
id
required
string

Data enhancement ID (enh_*)

header Parameters
Space
required
string

Space ID (spa_*)

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-enhancements/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5"
}

Get data enhancement

Get a data enhancement workspace by ID in the current space

path Parameters
id
required
string

Data enhancement ID (enh_*)

header Parameters
Space
required
string

Space ID (spa_*)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-enhancements/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "description": "Scores the active customer base every morning.",
  • "facts_count": 8,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "last_updated": "example",
  • "name": "churn-propensity-v3",
  • "predictions_count": 8,
  • "raw_dataset_ids": [
    ],
  • "status": "DRAFT",
  • "transformations_count": 8
}

Update data enhancement

Partial update of a data enhancement workspace in the current space

path Parameters
id
required
string

Data enhancement ID (enh_*)

header Parameters
Space
required
string

Space ID (spa_*)

Request Body schema: application/json
required

Update body

description
string
name
string
raw_dataset_ids
Array of strings
status
string
Enum: "DRAFT" "PROCESSING" "READY" "FAILED"

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "raw_dataset_ids": [
    ],
  • "status": "DRAFT"
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "description": "Scores the active customer base every morning.",
  • "facts_count": 8,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "last_updated": "example",
  • "name": "churn-propensity-v3",
  • "predictions_count": 8,
  • "raw_dataset_ids": [
    ],
  • "status": "DRAFT",
  • "transformations_count": 8
}

data-extractions

List data extractions

Returns the data extractions in the current space. Deleted

query Parameters
limit
integer
Default: 10

limit

after
string

after

status
string

comma-separated statuses

include_deleted
boolean

include soft-deleted extractions

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-extractions" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create data extraction

Submit a new extraction job. Returns the extraction in PENDING status.

Request Body schema: application/json
required

Data extraction creation request

description
string
name
required
string
required
object (request.ExtractionSource)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "source": {
    }
}

Response samples

Content type
application/json
{
  • "connector_id": "conn_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "deleted": false,
  • "deleted_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "output_dir": "/datasets/transactions",
  • "source": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Delete data extraction

Soft-delete a data extraction. The underlying neocore job is

path Parameters
id
required
string

Data extraction ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-extractions/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

Get data extraction

Retrieve a data extraction by ID.

path Parameters
id
required
string

Data extraction ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-extractions/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "connector_id": "conn_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "deleted": false,
  • "deleted_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "output_dir": "/datasets/transactions",
  • "source": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Rename / update data extraction

Update name and/or description. Source config is immutable.

path Parameters
id
required
string

Data extraction ID

Request Body schema: application/json
required

Update body

description
string
name
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "connector_id": "conn_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "deleted": false,
  • "deleted_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "output_dir": "/datasets/transactions",
  • "source": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "updated_at": "2026-01-15T10:30:00Z"
}

data-models

Get all data models

Retrieve a list of data models with pagination

query Parameters
limit
integer
Default: 10

limit

after
string

after

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-models" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create data model

Create a new data model

Request Body schema: application/json
required

Data model creation request

description
string
kind
required
string
Enum: "PRETRAIN" "POST_TRAINING"
name
required
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "kind": "PRETRAIN",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "name": "churn-propensity-v3",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Delete data model

Delete a data model by ID

path Parameters
id
required
string

Data model ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-models/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5"
}

Get data model

Retrieve a data model by ID

path Parameters
id
required
string

Data model ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-models/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "name": "churn-propensity-v3",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Update data model

Update a data model by ID

path Parameters
id
required
string

Data model ID

Request Body schema: application/json
required

Data model update request

description
string
name
string

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "name": "churn-propensity-v3",
  • "updated_at": "2026-01-15T10:30:00Z"
}

data-preprocesses

List data preprocesses

query Parameters
id
string

comma-separated preprocess ids (dpp_...); set limit to the id count to get them all in one page

profile_id
string

filter by parent profile

status
string

comma-separated statuses (include ARCHIVED to pull archived rows)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-preprocesses" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create data preprocess

Create a preprocess from a parent profile. Send EITHER

Request Body schema: application/json
required

Preprocess creation

excluded_columns
Array of strings
feature_columns
required
Array of strings non-empty

FeatureColumns are the primary-key columns that uniquely identify each row — required (at least one). TimestampColumn is the row's event-time column — required and non-empty (min=1 rejects a pointer to "").

included_columns
Array of strings
lineage_id
required
string

LineageID is the parent profile's lineage id. The backend always builds the preprocess from the latest version of that lineage (and rejects a stale, non-latest version id). Send the lineage_id from the profile.

name
required
string
object

Options is the optional advanced-settings block. Any field left nil falls back to the server-side default in mapper.DefaultPreprocessDatasetConfig.

target_columns
Array of strings
timestamp_column
required
string non-empty

Responses

Request samples

Content type
application/json
{
  • "excluded_columns": [
    ],
  • "feature_columns": [
    ],
  • "included_columns": [
    ],
  • "lineage_id": "string",
  • "name": "string",
  • "options": {
    },
  • "target_columns": [
    ],
  • "timestamp_column": "string"
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "excluded_columns": [
    ],
  • "feature_columns": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "max_event_ts": "example",
  • "min_event_ts": "example",
  • "n_cols": 1,
  • "n_rows": 1,
  • "name": "churn-propensity-v3",
  • "number_of_nodes": 2,
  • "outdated": false,
  • "processed_output": "example",
  • "profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_latest_version": 1,
  • "profile_lineage_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_name": "transactions-profile",
  • "profile_version": 1,
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "target_columns": [
    ],
  • "target_metric_columns": [
    ],
  • "timestamp_column": "2026-01-15T10:30:00Z",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Delete data preprocess

Hard-delete a data preprocess. Only FAILED preprocesses can be

path Parameters
id
required
string

Data preprocess ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-preprocesses/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

Get data preprocess

path Parameters
id
required
string

Data preprocess ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-preprocesses/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "excluded_columns": [
    ],
  • "feature_columns": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "max_event_ts": "example",
  • "min_event_ts": "example",
  • "n_cols": 1,
  • "n_rows": 1,
  • "name": "churn-propensity-v3",
  • "number_of_nodes": 2,
  • "outdated": false,
  • "processed_output": "example",
  • "profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_latest_version": 1,
  • "profile_lineage_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_name": "transactions-profile",
  • "profile_version": 1,
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "target_columns": [
    ],
  • "target_metric_columns": [
    ],
  • "timestamp_column": "2026-01-15T10:30:00Z",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Rename data preprocess

path Parameters
id
required
string

Data preprocess ID

Request Body schema: application/json
required

Update body

name
string

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "excluded_columns": [
    ],
  • "feature_columns": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "max_event_ts": "example",
  • "min_event_ts": "example",
  • "n_cols": 1,
  • "n_rows": 1,
  • "name": "churn-propensity-v3",
  • "number_of_nodes": 2,
  • "outdated": false,
  • "processed_output": "example",
  • "profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_latest_version": 1,
  • "profile_lineage_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_name": "transactions-profile",
  • "profile_version": 1,
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "target_columns": [
    ],
  • "target_metric_columns": [
    ],
  • "timestamp_column": "2026-01-15T10:30:00Z",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Approve a data preprocess for auto-merge

Mark a PROCESSED preprocess to auto-merge into a target profile version when that version is promoted drift-free.

path Parameters
id
required
string

Data preprocess ID

Request Body schema: application/json
required

Target profile version

target_profile_id
required
string

Responses

Request samples

Content type
application/json
{
  • "target_profile_id": "string"
}

Response samples

Content type
application/json
{
  • "error": "example"
}

Archive data preprocess

path Parameters
id
required
string

Data preprocess ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-preprocesses/{id}/archive" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

Get data preprocess columns

Returns the persisted column snapshot — the columns the user

path Parameters
id
required
string

Data preprocess ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-preprocesses/{id}/columns" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Copy data preprocess to another space

Clones a PROCESSED preprocess and its parent profile into

path Parameters
id
required
string

Data preprocess ID

Request Body schema: application/json
required

Target space

target_space
required
string

Responses

Request samples

Content type
application/json
{
  • "target_space": "string"
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "excluded_columns": [
    ],
  • "feature_columns": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "max_event_ts": "example",
  • "min_event_ts": "example",
  • "n_cols": 1,
  • "n_rows": 1,
  • "name": "churn-propensity-v3",
  • "number_of_nodes": 2,
  • "outdated": false,
  • "processed_output": "example",
  • "profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_latest_version": 1,
  • "profile_lineage_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_name": "transactions-profile",
  • "profile_version": 1,
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "target_columns": [
    ],
  • "target_metric_columns": [
    ],
  • "timestamp_column": "2026-01-15T10:30:00Z",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Run a data preprocess merge

(Re-)run a preprocess as an incremental append-merge against a target profile version (default: latest of its lineage). Manual counterpart to auto-merge — use to recover from a failed merge or to merge on demand.

path Parameters
id
required
string

Data preprocess ID

Request Body schema: application/json

Target profile version (optional)

number_of_nodes
integer

NumberOfNodes optionally overrides the multi-node scaling for this run. nil reuses the value persisted on the preprocess (the last one used); a non-nil value both drives this run and becomes the new "last used". Validated >= 1 in the handler, mirroring PreprocessOptions.Validate.

target_profile_id
string

Responses

Request samples

Content type
application/json
{
  • "number_of_nodes": 0,
  • "target_profile_id": "string"
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "excluded_columns": [
    ],
  • "feature_columns": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "max_event_ts": "example",
  • "min_event_ts": "example",
  • "n_cols": 1,
  • "n_rows": 1,
  • "name": "churn-propensity-v3",
  • "number_of_nodes": 2,
  • "outdated": false,
  • "processed_output": "example",
  • "profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_latest_version": 1,
  • "profile_lineage_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "profile_name": "transactions-profile",
  • "profile_version": 1,
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "target_columns": [
    ],
  • "target_metric_columns": [
    ],
  • "timestamp_column": "2026-01-15T10:30:00Z",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Revoke a data preprocess auto-merge approval

Clear the auto-merge target on a preprocess.

path Parameters
id
required
string

Data preprocess ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-preprocesses/{id}/unapprove" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

Unarchive data preprocess

Restore an archived data preprocess to its active state.

path Parameters
id
required
string

Data preprocess ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-preprocesses/{id}/unarchive" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

data-profiles

List data profiles

Returns the data profiles in the current space. Archived

query Parameters
limit
integer
Default: 10

limit

after
string

after

status
string

comma-separated statuses (include ARCHIVED to pull archived rows)

structure
string

comma-separated structures

pending_drift
boolean

only lineages with a DRIFT_BLOCKED version awaiting review (not reachable via status: a blocked version is never the lineage head)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create data profile

Submit a new profiling job. Returns the profile in PENDING status.

Request Body schema: application/json
required

Data profile creation request

description
string
object

Metrics optionally overrides the scan's drift policy (injected as the top-level metrics block in the scan config) and is persisted on the profile so appends reuse it.

required
Array of objects (request.DataProfileFile) non-empty
name
required
string
object

Options is the optional advanced-settings block. Any field left nil falls back to the server-side default in mapper.DefaultProfileScanBaseConfig.

structure
required
string (model.DataProfileStructure)
Enum: "EVENT_BASED" "FEATURE_BASED" "FILTER_BASED"

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "drift_metrics": {
    },
  • "files": [
    ],
  • "name": "string",
  • "options": {
    },
  • "structure": "EVENT_BASED"
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "cast_columns": [
    ],
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "drift_approved_at": "2026-01-15T10:30:00Z",
  • "drift_detected_at": "2026-01-15T10:30:00Z",
  • "drift_mergeable": false,
  • "drift_metrics": {
    },
  • "drift_reason_code": "Example message",
  • "drift_rejected_at": "2026-01-15T10:30:00Z",
  • "favorite": false,
  • "files": [
    ],
  • "folder_id": "fld_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "is_latest": false,
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "materializations_count": 8,
  • "name": "churn-propensity-v3",
  • "quality_summary": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "version": 1
}

Delete data profile

Hard-delete a data profile. Only FAILED profiles can be deleted —

path Parameters
id
required
string

Data profile ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

Get data profile

Retrieve a data profile by ID.

path Parameters
id
required
string

Data profile ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "cast_columns": [
    ],
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "drift_approved_at": "2026-01-15T10:30:00Z",
  • "drift_detected_at": "2026-01-15T10:30:00Z",
  • "drift_mergeable": false,
  • "drift_metrics": {
    },
  • "drift_reason_code": "Example message",
  • "drift_rejected_at": "2026-01-15T10:30:00Z",
  • "favorite": false,
  • "files": [
    ],
  • "folder_id": "fld_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "is_latest": false,
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "materializations_count": 8,
  • "name": "churn-propensity-v3",
  • "quality_summary": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "version": 1
}

Rename / update data profile

Update name and/or description. Files and structure are immutable.

path Parameters
id
required
string

Data profile ID

Request Body schema: application/json
required

Update body

description
string
name
string
structure
string (model.DataProfileStructure)
Enum: "EVENT_BASED" "FEATURE_BASED" "FILTER_BASED"

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "structure": "EVENT_BASED"
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "cast_columns": [
    ],
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "drift_approved_at": "2026-01-15T10:30:00Z",
  • "drift_detected_at": "2026-01-15T10:30:00Z",
  • "drift_mergeable": false,
  • "drift_metrics": {
    },
  • "drift_reason_code": "Example message",
  • "drift_rejected_at": "2026-01-15T10:30:00Z",
  • "favorite": false,
  • "files": [
    ],
  • "folder_id": "fld_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "is_latest": false,
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "materializations_count": 8,
  • "name": "churn-propensity-v3",
  • "quality_summary": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "version": 1
}

Approve a drift-blocked profile version

Accept the drift detected on a DRIFT_BLOCKED version. Submits the engine merge_info action to consume the staged batch and bump the version; the version returns to PENDING while the merge runs, and is promoted (drift-free) by the webhook on completion.

path Parameters
id
required
string

Drift-blocked profile version ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/approve-drift" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "cast_columns": [
    ],
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "drift_approved_at": "2026-01-15T10:30:00Z",
  • "drift_detected_at": "2026-01-15T10:30:00Z",
  • "drift_mergeable": false,
  • "drift_metrics": {
    },
  • "drift_reason_code": "Example message",
  • "drift_rejected_at": "2026-01-15T10:30:00Z",
  • "favorite": false,
  • "files": [
    ],
  • "folder_id": "fld_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "is_latest": false,
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "materializations_count": 8,
  • "name": "churn-propensity-v3",
  • "quality_summary": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "version": 1
}

Archive data profile

Soft-archive a data profile. Profiles are never hard-deleted —

path Parameters
id
required
string

Data profile ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/archive" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

Recast data profile columns

Recast one or more columns of a profile lineage to a new type, producing a new incremental version. Source-type/transition validation is delegated to the engine; an illegal cast surfaces as a FAILED version.

path Parameters
id
required
string

Data profile lineage ID

Request Body schema: application/json
required

Columns to recast

Array of objects (request.ApprovePreprocessTarget)

ApprovePreprocesses optionally pre-approves already-PROCESSED datasets (built from this profile) to auto-merge into the new cast version once it is promoted — same mechanism as AppendDataProfileVersion, each carrying its own node count. Non-PROCESSED ids are ignored by the repository's status guard.

required
Array of objects (request.CastColumnSpec) non-empty
object

Options tunes the cast (re-scan) job — same knobs as AppendVersion, e.g. number_of_nodes to scale the recast across a multi-node Spark cluster. nil falls back to the server-side defaults.

Responses

Request samples

Content type
application/json
{
  • "approve_preprocesses": [
    ],
  • "columns": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "cast_columns": [
    ],
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "drift_approved_at": "2026-01-15T10:30:00Z",
  • "drift_detected_at": "2026-01-15T10:30:00Z",
  • "drift_mergeable": false,
  • "drift_metrics": {
    },
  • "drift_reason_code": "Example message",
  • "drift_rejected_at": "2026-01-15T10:30:00Z",
  • "favorite": false,
  • "files": [
    ],
  • "folder_id": "fld_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "is_latest": false,
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "materializations_count": 8,
  • "name": "churn-propensity-v3",
  • "quality_summary": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "version": 1
}

Get a data profile column's value distribution

One page of a single column's value distribution (value, count,

path Parameters
id
required
string

Data profile lineage ID

query Parameters
column
required
string

Column name (URL-encoded)

version
integer

Profile version (default: latest)

search
string

Case-insensitive substring filter on the value

limit
integer

Page size (default 100, max 1000)

offset
integer

Page offset

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/columns?column=COLUMN" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": {
    },
  • "has_more": false,
  • "rows_count": 8,
  • "total": 1,
  • "values": [
    ]
}

Get a drift-blocked version's drift result

Full drift_result.json a drift-blocking scan produced for a DRIFT_BLOCKED (or DRIFT_REJECTED) version — verdict, per-column findings with inline detail, and the metric roll-up. Lets the frontend review the drift before approving or rejecting. Read live from neocore.

path Parameters
id
required
string

Drift-blocked version ID

query Parameters
batch_id
string

Staged batch id (defaults to the version's)

search
string

Substring filter on a finding's column

regex
string

Regex filter on a finding's column (takes precedence over search)

varType
Array of strings

Filter findings by column kind (numeric/categorical)

limit
integer

Page size (default 20)

offset
integer

Page offset

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/drift" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "findings": [
    ],
  • "has_more": false,
  • "metrics": [
    ],
  • "run": {
    },
  • "total": 1,
  • "verdict": {
    }
}

Get data profile quality history

Per-version dataset-quality summary trend (ascending by version) for a lineage, cursor-paginated. Pass the last row's id as after for the next page.

path Parameters
id
required
string

Data profile lineage ID

query Parameters
limit
integer

Page size (default 20, max 100)

after
string

Cursor: id of the previous page's last version (exclusive)

order
string

Sort direction: 'asc' or 'desc' (default 'asc')

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/quality-history" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false
}

Reject a drift-blocked profile version

Reject the drift detected on a DRIFT_BLOCKED version. The staged batch is abandoned (never merged), the lineage head is untouched, and the version is marked DRIFT_REJECTED with the supplied reason. Being terminal, it frees the lineage for a new append (after the source is fixed).

path Parameters
id
required
string

Drift-blocked profile version ID

Request Body schema: application/json
required

Rejection reason

reason
required
string

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "cast_columns": [
    ],
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "drift_approved_at": "2026-01-15T10:30:00Z",
  • "drift_detected_at": "2026-01-15T10:30:00Z",
  • "drift_mergeable": false,
  • "drift_metrics": {
    },
  • "drift_reason_code": "Example message",
  • "drift_rejected_at": "2026-01-15T10:30:00Z",
  • "favorite": false,
  • "files": [
    ],
  • "folder_id": "fld_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "is_latest": false,
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "materializations_count": 8,
  • "name": "churn-propensity-v3",
  • "quality_summary": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "version": 1
}

Get data profile stats

Live column statistics from neocore. Used for the

path Parameters
id
required
string

Data profile lineage ID

query Parameters
version
integer

Profile version (default: latest)

search
string

Substring filter

regex
string

Regex filter (takes precedence over search)

limit
integer

Page size

offset
integer

Page offset

sort
string
Default: "name"
Enum: "name" "null_count"

Ranking key applied before pagination

order
string
Default: "asc"
Enum: "asc" "desc"

Ranking direction

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/stats" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "after": "1a2b3c4d5e6f708192a3b4c5",
  • "data": [
    ],
  • "has_more": false,
  • "rows_count": 8,
  • "sampled_rows_count": 8,
  • "total": 1
}

One (column, period) temporal quality cell

The drill-down cell: the period's screen stats, histogram/class counts and drift row (entry, verbatim from the engine) plus the rulers they were measured over (hist for numeric, classes for categorical). Cells exist at the lineage's NATIVE granularity only — period must be a native-axis label; no period format is enforced, a period that was never measured is simply a 404.

path Parameters
id
required
string

Data profile lineage ID

query Parameters
column
required
string

Column name

period
required
string

Period (e.g. 1991-01-07)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/temporal-quality/cell?column=COLUMN&period=PERIOD" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "classes": { },
  • "column": "event_ts",
  • "entry": { },
  • "granularity": "example",
  • "hist": { },
  • "kind": "example",
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "period": "example",
  • "run_id": "bif_1a2b3c4d5e6f708192a3b4c5",
  • "state_version": 1
}

One column's temporal quality series

The full series document for one column: all six metric arrays (psi/jsd/tvd and their _prev twins) parallel to the column's periods axis, plus verdict and flags. granularity selects which axis (default: finest available); start/end window it. The column is a query parameter because column names are free-form (a name may contain "/").

path Parameters
id
required
string

Data profile lineage ID

query Parameters
column
required
string

Column name

granularity
string

day|week|month (default: finest available)

start
string

Window start period (inclusive)

end
string

Window end period (inclusive)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/temporal-quality/column?column=COLUMN" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "approximate": false,
  • "approximate_reason": "Example message",
  • "column": "event_ts",
  • "flagged_by": {
    },
  • "flagged_periods": [
    ],
  • "granularity": "example",
  • "jsd": [
    ],
  • "jsd_prev": [
    ],
  • "kind": "example",
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "periods": [
    ],
  • "psi": [
    ],
  • "psi_prev": [
    ],
  • "run_id": "bif_1a2b3c4d5e6f708192a3b4c5",
  • "state_version": 1,
  • "tvd": [
    ],
  • "tvd_prev": [
    ],
  • "verdict": "example"
}

One column's temporal quality profile

The column detail panel's feed: per-bucket volume/count/null arrays at the selected granularity plus the window's summary cards, with the class composition (categorical) or histogram (numeric) per bucket. Coarse buckets are exact read-time aggregations of the native per-period stats; drift metrics stay on /column and /heatmap (real per-granularity scores from the engine, never aggregated). start/end are inclusive bucket labels at the selected granularity.

path Parameters
id
required
string

Data profile lineage ID

query Parameters
column
required
string

Column name

granularity
string

day|week|month (default: finest available)

start
string

Window start bucket (inclusive, YYYY-MM-DD)

end
string

Window end bucket (inclusive, YYYY-MM-DD)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/temporal-quality/column-profile?column=COLUMN" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "classes_series": {
    },
  • "column": "event_ts",
  • "count": [
    ],
  • "granularity": "example",
  • "hist": {
    },
  • "kind": "example",
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "null_count": [
    ],
  • "periods": [
    ],
  • "run_id": "bif_1a2b3c4d5e6f708192a3b4c5",
  • "state_version": 1,
  • "totals": {
    },
  • "volume": [
    ]
}

Temporal quality heatmap

The lineage's periods axis, volume and header plus each column's PSI series and flagged periods — the heatmap feed. granularity selects which axis (available_granularities lists the lineage's options; default = finest available). start/end (inclusive period strings) window the axis and every parallel array; n_periods/n_columns keep echoing the full-axis header. 404 until the first completed run pushes its view.

path Parameters
id
required
string

Data profile lineage ID

query Parameters
granularity
string

day|week|month (default: finest available)

start
string

Window start period (inclusive, e.g. 1991-01-07)

end
string

Window end period (inclusive)

columns_limit
integer

Column page size, worst drift first (default 50, max 500; 0 = the axis only)

columns_offset
integer

Column page offset

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/temporal-quality/heatmap" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "available_granularities": [
    ],
  • "columns": [
    ],
  • "columns_has_more": false,
  • "drift": { },
  • "event_ts_col": "example",
  • "granularity": "example",
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "n_columns": 1,
  • "n_periods": 1,
  • "periods": [
    ],
  • "run_id": "bif_1a2b3c4d5e6f708192a3b4c5",
  • "sampling": { },
  • "scan_mode": "example",
  • "state_version": 1,
  • "volume": [
    ]
}

List temporal quality runs

The lineage's run history, newest first, cursor-paginated.

path Parameters
id
required
string

Data profile lineage ID

query Parameters
after
string

Cursor: id of the previous page's last run

limit
integer

Page size (default 20, max 100)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/temporal-quality/runs" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false
}

Start a temporal quality run

Submit a temporal quality job over the lineage head's files. The body is optional: an empty body folds whatever data is new into the accumulated state with the lineage's locked config. event_ts_col (+ scan_mode) is required when cold-starting (first run or rebuild); start_date/end_date bound the event-time window this run analyzes; update_ref_period sent alone re-scores drift from the saved state against a new reference (no data read), and sent with a cold start it seeds the fresh state's reference. Unknown body keys are rejected with a 400.

path Parameters
id
required
string

Data profile lineage ID

Request Body schema: application/json

Run options: cold-start config (event_ts_col, scan_mode, sample_max_rows, rebuild), this run's event-time window (start_date, end_date) and/or the drift reference (update_ref_period)

end_date
string
event_ts_col
string

EventTSColumn names the event-time axis. Required on the FIRST run of a lineage only — a rule that needs the lineage's history, so the service (not a binding tag) enforces it; later runs reuse the stored column.

rebuild
boolean

Rebuild discards the accumulated state and cold-starts the lineage with THIS request's EventTSColumn/ScanMode — the only way to change them. The engine drops the persisted drift reference with the state: send UpdateRefPeriod on the rebuild to keep a moved reference.

sample_max_rows
integer

SampleMaxRows is the approximate row count a sample run reads (the engine derives the sampling fraction from it). Required — and only allowed — when ScanMode is "sample". Locked together with ScanMode.

scan_mode
string

ScanMode is "full" or "sample". Like EventTSColumn it is lineage-locked engine-side: decided on the first run (empty = "full"), reused on later runs, changeable only via Rebuild.

start_date
string

StartDate/EndDate bound the event-time window THIS run analyzes ("YYYY-MM-DD", inclusive at both ends; either side may be absent = unbounded). Unlike the fields above they are per-run intent: never lineage-locked, never inherited from a previous run — an empty side means unbounded, not "reuse the last run's window". The engine's batch ledger rejects a window overlapping data already folded from the same files.

object

UpdateRefPeriod moves the drift reference: the engine scores every period outside this range against the periods inside it, republishes every document, and persists the range in its state so later data runs keep scoring against it (until the next move). Two shapes:

  • ALONE: a recompute — the engine re-scores the whole timeline from its saved state and reads no data. It needs a completed run, and any other field present is a 400, including values that merely echo the lineage lock (stricter than a plain rerun, which tolerates agreeing echoes).
  • WITH A COLD START (first run, or Rebuild): a data run that seeds the fresh state's reference. A rebuild drops the persisted reference engine-side, so this is how a moved reference survives one; omitted, the rebuilt state scores against the default earliest-periods baseline. On a warm lineage without Rebuild it cannot accompany any other field.

Responses

Request samples

Content type
application/json
{
  • "end_date": "string",
  • "event_ts_col": "string",
  • "rebuild": true,
  • "sample_max_rows": 0,
  • "scan_mode": "string",
  • "start_date": "string",
  • "update_ref_period": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "end_date": "example",
  • "event_ts_col": "example",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "rebuild": false,
  • "sample_max_rows": 4,
  • "scan_mode": "example",
  • "start_date": "2026-01-01T00:00:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "update_ref_period": {
    },
  • "updated_at": "2026-01-15T10:30:00Z"
}

Get one temporal quality run

path Parameters
id
required
string

Data profile lineage ID

runId
required
string

Temporal quality run ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/temporal-quality/runs/{runId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "end_date": "example",
  • "event_ts_col": "example",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "rebuild": false,
  • "sample_max_rows": 4,
  • "scan_mode": "example",
  • "start_date": "2026-01-01T00:00:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "update_ref_period": {
    },
  • "updated_at": "2026-01-15T10:30:00Z"
}

Unarchive data profile

Restore an archived data profile to its active state.

path Parameters
id
required
string

Data profile ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/unarchive" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

List data profile versions

Page of a logical profile's versions in chronological order (newest first by creation time), addressed by lineage ID (the lineage_id from any profile response). Includes non-READY attempts (FAILED / DRIFT_REJECTED / etc.) interleaved in time order. Cursor pagination by id: pass the last row's id as after.

path Parameters
id
required
string

Data profile lineage ID

query Parameters
limit
integer

Page size (default 20, max 100)

after
string

Cursor: id of the previous page's last version (exclusive)

order
string

Sort direction: 'asc' or 'desc' (default 'desc')

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/versions" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false
}

Append a data profile version

Append new connector paths to an existing profile lineage, producing a new incremental version. Optionally pre-approve PROCESSED preprocesses to auto-merge into it.

path Parameters
id
required
string

Data profile lineage ID

Request Body schema: application/json
required

New paths (+ optional approvals)

Array of objects (request.ApprovePreprocessTarget)
object (request.ProfileOptions)

Responses

Request samples

Content type
application/json
{
  • "approve_preprocesses": [
    ],
  • "options": {
    }
}

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "cast_columns": [
    ],
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "drift_approved_at": "2026-01-15T10:30:00Z",
  • "drift_detected_at": "2026-01-15T10:30:00Z",
  • "drift_mergeable": false,
  • "drift_metrics": {
    },
  • "drift_reason_code": "Example message",
  • "drift_rejected_at": "2026-01-15T10:30:00Z",
  • "favorite": false,
  • "files": [
    ],
  • "folder_id": "fld_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "is_latest": false,
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "materializations_count": 8,
  • "name": "churn-propensity-v3",
  • "quality_summary": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "version": 1
}

Get one data profile version

A single version of a logical profile, addressed by lineage ID + version number.

path Parameters
id
required
string

Data profile lineage ID

version
required
integer

Version number

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/data-profiles/{id}/versions/{version}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "archived": false,
  • "archived_at": "2026-01-15T10:30:00Z",
  • "cast_columns": [
    ],
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "drift_approved_at": "2026-01-15T10:30:00Z",
  • "drift_detected_at": "2026-01-15T10:30:00Z",
  • "drift_mergeable": false,
  • "drift_metrics": {
    },
  • "drift_reason_code": "Example message",
  • "drift_rejected_at": "2026-01-15T10:30:00Z",
  • "favorite": false,
  • "files": [
    ],
  • "folder_id": "fld_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "is_latest": false,
  • "lineage_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "materializations_count": 8,
  • "name": "churn-propensity-v3",
  • "quality_summary": {
    },
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "structure": "EVENT_BASED",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "version": 1
}

dna

List the bases the DNA pipeline consumes

The catalog an operator picks sources from: key, hive partition prefix, whether a preprocessed form exists, and the tolerated staleness. Served from the API rather than duplicated in the front-end so the screen and the pipeline have one place to agree.

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/dna-bases" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "items": [
    ]
}

List DNA runs

Runs newest first, with the status refreshed from the cluster for the ones still in flight. Progress figures come from the last detail read — the listing costs one cluster call regardless of how many runs are on the page.

query Parameters
space_id
string

Narrow to one space

status
string

Comma-separated statuses

limit
integer

Maximum rows

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/dna-runs" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "items": [
    ]
}

Start a DNA run

Submits the three roles of the chain (input, N inference shards, analysis) as separate neocore jobs. The sources are re-resolved server-side before anything is submitted, so a pre-flight that has gone stale is refused rather than run.

Request Body schema: application/json
required

Run configuration

chunk_size
required
integer >= 1
data_ref
string

VAZIA = derivada da dat_cria_exeo da tabela de execução, que é o default. Preenchida só quando o operador quer ancorar o run noutra data: o pipeline então usa a dele e AVISA se divergir da origem. Obrigatória aqui era o que matava a derivação -- ela só roda quando a data não vem, e a tela mandava sempre.

deadline
string

Deadline is advisory — it is recorded so the shard count has a stated reason. Format YYYY-MM-DD. Meaningless on a streaming run (there is no end to be late for), so it is refused together with it.

endpoint_id
string

O servidor de modelo vem por UMA das duas formas, nunca pelas duas -- escolherFormaDoModelo recusa a ambiguidade em vez de eleger uma.

EndpointID: a plataforma resolve endereço e nome do modelo, e é a única forma em que "rodar de novo" re-resolve o endereço quando a frota muda de lugar. Por isso nenhum dos dois é required aqui: a exigência é "um dos dois", que o binding de campo não expressa.

endpoint_url
string

EndpointURL aponta um vLLM que não é endpoint desta plataforma. Aceita CSV, como o comum/endpoints.py do driver (round-robin + failover).

history_months
required
integer [ 1 .. 120 ]
name
required
string <= 63 characters

Sem space_id: a space vem do PATH. Ela existia aqui quando a tela morava no hub de admin, que não tem space na URL -- e ter a space em dois lugares é ter dois que podem discordar.

output_connector_id
string

OutputConnectorID names an S3 (or instance-profile) data integration to write the result to, DIRECTLY — no staging copy. It may be the same integration as the queue's or a different one.

output_path
string

OutputPath is where the analysis role writes the consolidated parquet. Empty keeps it under the run's own work root. With OutputConnectorID it is the prefix inside that connector's bucket.

output_version
required
string <= 63 characters
required
object (request.DNAQueueInput)
served_model_name
string

ServedModelName é obrigatório JUNTO de EndpointURL: --model tem que bater com o --served-model-name do servidor, e desta API não há como perguntar a um endereço in-cluster.

shards
required
integer [ 1 .. 64 ]
required
Array of objects (request.DNASourceInput) non-empty
streaming
boolean

Streaming makes the run ETERNAL: the input role keeps watching the queue instead of doing a single pass, and the inference shards stop exiting when they drain the shelf. It is a CHOICE, not a default — a run that cannot end has no percent, no ETA and no deadline, so the screen shows a different set of numbers (rate and shelf depth) and the only way out is canceling it.

Responses

Request samples

Content type
application/json
{
  • "chunk_size": 1,
  • "data_ref": "string",
  • "deadline": "string",
  • "endpoint_id": "string",
  • "endpoint_url": "string",
  • "history_months": 1,
  • "name": "string",
  • "output_connector_id": "string",
  • "output_path": "string",
  • "output_version": "string",
  • "queue": {
    },
  • "served_model_name": "string",
  • "shards": 1,
  • "sources": [
    ],
  • "streaming": true
}

Response samples

Content type
application/json
{
  • "chunk_size": 1,
  • "cluster": "example",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_ref": "example",
  • "deadline": "example",
  • "endpoint_id": "mep_1a2b3c4d5e6f708192a3b4c5",
  • "endpoint_url": "https://example.com/path",
  • "finished_at": "2026-01-15T10:30:00Z",
  • "history_months": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "jobs": [
    ],
  • "name": "churn-propensity-v3",
  • "output_connector_id": "conn_1a2b3c4d5e6f708192a3b4c5",
  • "output_endpoint": "https://example.com/path",
  • "output_path": "/datasets/transactions",
  • "output_region": "example",
  • "output_secret_id": "sec_1a2b3c4d5e6f708192a3b4c5",
  • "output_version": "1.0.0",
  • "progress": {
    },
  • "queue": {
    },
  • "queue_in": {
    },
  • "served_model_name": "churn-propensity",
  • "shard_details": [
    ],
  • "shards": 1,
  • "sources": [
    ],
  • "space": "example",
  • "stages": [
    ],
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "Pending",
  • "status_reason": "Example message",
  • "streaming": false,
  • "work_root": "example"
}

Resolve what a run would read

Resolves every source and the queue before any job exists, and separates BLOCKERS (which stop the submit) from WARNINGS (the operator's call). It exists because this pipeline's failures are silent: a base with no partition for the day returns a months-old snapshot, an empty queue processes zero clients without an error.

Request Body schema: application/json
required

Configuration to resolve

data_ref
required
string
endpoint_id
string

Opcional: o pré-flight resolve FONTE e FILA, não o modelo. Uma execução apontada para uma URL manual simplesmente não o manda.

history_months
integer
required
object

Sem space_id, pela mesma razão do Create: a space é o path.

required
Array of objects (request.DNASourceInput) non-empty

Responses

Request samples

Content type
application/json
{
  • "data_ref": "string",
  • "endpoint_id": "string",
  • "history_months": 0,
  • "queue": {
    },
  • "sources": [
    ]
}

Response samples

Content type
application/json
{
  • "blockers": [
    ],
  • "queue": {
    },
  • "sources": [
    ],
  • "warnings": [
    ]
}

Get one DNA run

One run in depth: aggregate progress and per-shard state, read live from the jobs' own reports and persisted as they are observed — the final metrics live in the jobs' outputs, and the cluster eventually deletes the jobs.

path Parameters
runId
required
string

Run ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/dna-runs/{runId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "chunk_size": 1,
  • "cluster": "example",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_ref": "example",
  • "deadline": "example",
  • "endpoint_id": "mep_1a2b3c4d5e6f708192a3b4c5",
  • "endpoint_url": "https://example.com/path",
  • "finished_at": "2026-01-15T10:30:00Z",
  • "history_months": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "jobs": [
    ],
  • "name": "churn-propensity-v3",
  • "output_connector_id": "conn_1a2b3c4d5e6f708192a3b4c5",
  • "output_endpoint": "https://example.com/path",
  • "output_path": "/datasets/transactions",
  • "output_region": "example",
  • "output_secret_id": "sec_1a2b3c4d5e6f708192a3b4c5",
  • "output_version": "1.0.0",
  • "progress": {
    },
  • "queue": {
    },
  • "queue_in": {
    },
  • "served_model_name": "churn-propensity",
  • "shard_details": [
    ],
  • "shards": 1,
  • "sources": [
    ],
  • "space": "example",
  • "stages": [
    ],
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "Pending",
  • "status_reason": "Example message",
  • "streaming": false,
  • "work_root": "example"
}

Stop a DNA run

Cancels the run's jobs. What was already written STAYS — the output is per chunk, so a later run resumes from where this one stopped.

path Parameters
runId
required
string

Run ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/dna-runs/{runId}/cancel" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "chunk_size": 1,
  • "cluster": "example",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "data_ref": "example",
  • "deadline": "example",
  • "endpoint_id": "mep_1a2b3c4d5e6f708192a3b4c5",
  • "endpoint_url": "https://example.com/path",
  • "finished_at": "2026-01-15T10:30:00Z",
  • "history_months": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "jobs": [
    ],
  • "name": "churn-propensity-v3",
  • "output_connector_id": "conn_1a2b3c4d5e6f708192a3b4c5",
  • "output_endpoint": "https://example.com/path",
  • "output_path": "/datasets/transactions",
  • "output_region": "example",
  • "output_secret_id": "sec_1a2b3c4d5e6f708192a3b4c5",
  • "output_version": "1.0.0",
  • "progress": {
    },
  • "queue": {
    },
  • "queue_in": {
    },
  • "served_model_name": "churn-propensity",
  • "shard_details": [
    ],
  • "shards": 1,
  • "sources": [
    ],
  • "space": "example",
  • "stages": [
    ],
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "Pending",
  • "status_reason": "Example message",
  • "streaming": false,
  • "work_root": "example"
}

drift-policies

List drift policies

Retrieve drift policies in the current space with pagination

query Parameters
limit
integer
Default: 10

limit

after
string

after

name
string

name filter

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/drift-policies" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create drift policy

Create a new drift policy in the current space

Request Body schema: application/json
required

Drift policy creation request

description
string
name
required
string
object (model.DriftMetrics)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "policy": {
    },
  • "updated_at": "2026-01-15T10:30:00Z"
}

Delete drift policy

Delete a drift policy by ID

path Parameters
id
required
string

Drift policy ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/drift-policies/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5"
}

Get drift policy

Retrieve a drift policy by ID

path Parameters
id
required
string

Drift policy ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/drift-policies/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "policy": {
    },
  • "updated_at": "2026-01-15T10:30:00Z"
}

Update drift policy

Update a drift policy by ID

path Parameters
id
required
string

Drift policy ID

Request Body schema: application/json
required

Drift policy update request

description
string
name
string
object (model.DriftMetrics)

Responses

Request samples

Content type
application/json
{
  • "description": "string",
  • "name": "string",
  • "policy": {
    }
}

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "description": "Scores the active customer base every morning.",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "policy": {
    },
  • "updated_at": "2026-01-15T10:30:00Z"
}

evaluations

Create evaluation

Create a new evaluation

Request Body schema: application/json
required

Evaluation creation request

benchmark_id
required
string
checkpoint_id
required
string
gpu_count
required
integer

Responses

Request samples

Content type
application/json
{
  • "benchmark_id": "string",
  • "checkpoint_id": "string",
  • "gpu_count": 0
}

Response samples

Content type
application/json
{
  • "benchmark_id": "ben_1a2b3c4d5e6f708192a3b4c5",
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "gpu_count": 8,
  • "id": "eva_1a2b3c4d5e6f708192a3b4c5",
  • "result": { },
  • "updated_at": "2026-01-15T10:30:00Z",
  • "updated_by": "example"
}

inference-servers

List inference servers

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create inference server

Request Body schema: application/json
required

Body

architecture
string <= 128 characters

Architecture names which platform architecture the model was trained under, for a path/datavolume deploy that has NO checkpoint lineage. It supplies the inference config (rust image + tunables) AND the cortex image the GPU engines run in (always multi-version — the training cortex, never cortex-infer-gpu) — the provenance a lineage-free deploy otherwise lacks. Empty → the platform's current default architecture (the most recent cortex). Ignored for a checkpoint source (which resolves the architecture from the checkpoint's training lineage).

object

AutoBatchConfig is the batch-mode automation intent (input source + schedule

  • no-new-files behavior). Previously the decoder dropped it.
checkpoint_id
string
compile
boolean

Compile is the torch.compile override for every engine role (embedding, backbone, fused). Omitted compiles; an explicit false runs the engines eager. Engine-only — it never reaches the context store.

compile_mode
string
Enum: "regional" "max-autotune"

CompileMode is the torch.compile mode the FUSED engine uses when Compile is on: "regional" (the default) or "max-autotune". "whole" is intentionally not offered (documented broken). The embedding and backbone engines always compile regionally.

object

Connectors carries the server's optional input data integrations. It is no longer required — the output destination moved to the batch run — so a deploy that sends none (or only inputs) is accepted.

cortex_image
string <= 512 characters

CortexImage optionally overrides the GPU/training cortex image the engines run in (the multi-version main container) — a full image ref typed by hand for a path/datavolume deploy. Empty → the architecture's image. Ignored for a checkpoint source (which resolves the image from its training lineage).

data_model_id
string

The lineage IDs are required only for the default checkpoint source; the lineage-free sources (path, datavolume) omit them. gin's required_unless takes a single value, so the "checkpoint source requires lineage" rule is enforced in the service Create instead (same rejection, better message) — the binding leaves them optional.

datavolume_name
string

DataVolumeName is the neocore DataVolume to serve the model from, required when model_source is "datavolume". DataVolumeSubpath is the optional dir under its mount the model lives in (empty = the mount root).

datavolume_subpath
string
object

EmbeddingQuant is the optional TurboQuant embedding-quantization knob. Absent → no quantization (emitted configs are byte-identical to before). Only online deploys carry it (folded into the model fingerprint across the engines + context store + server). Scheme/Bits/Seed/Rounds default server-side when omitted; Enabled defaults false.

object

Endpoint optionally fixes the online server's client-facing external port at deploy (online only): a specific port or a range to draw one from. Absent → neocore auto-allocates. Persisted as the server's desired port and pinned when the online HTTP server is brought up.

object

EngineScaling is the optional autoscaling config for the GPU engine tier (embedding + backbone). Absent → fixed single-replica engine jobs.

object

EngineYaml carries optional per-role user-edited engine config documents — the advanced "edit engine YAML" deploy mode — keyed by engine role: "embedding"/"backbone" for a split server, "fused" for a fused server. For each role present, the engine job mounts the user's document with the platform-managed engine fields (model dir, mode, embed_dtype, transport wiring, embedding_quant) deep-merged OVER it, so the operator can't break serving. Roles not present (or an empty string / absent map) fall back to the field-derived config — byte-identical to a deploy made before this knob existed. Malformed YAML → 400. Unknown role keys → 400.

inference_type
required
string
Enum: "batch" "online"
inference_version
string <= 128 characters

InferenceVersion overrides the cortex-infer image tag (tag only, e.g. "v0.0.8"); empty = the architecture's tag (latest). Validated tag-only in the service.

instances
integer
mode
string
Enum: "online" "batch" "hybrid"

Mode is the deploy intent: "online" (serves /infer), "hybrid" (serves /infer AND accepts batch runs through its engines, which default to the engine's batch mode — the portal's "Batch" deploy) or "batch" (accepts batch runs, no endpoint). It must agree with inference_type (online and hybrid are online types), and omitted derives from it.

model_path
string

ModelPath is the operator-supplied absolute model dir, required when model_source is "path". Must be under a shared volume (/shared or /mnt/fss).

model_source
string
Enum: "checkpoint" "path" "datavolume"

ModelSource selects where the served model dir comes from: "checkpoint" (the default; empty is treated as checkpoint) resolves the data-model / training / checkpoint lineage, "path" serves ModelPath directly (no lineage), or "datavolume" serves a dir under a neocore DataVolume's mount (no lineage).

object

Scaling is the optional autoscaling config for an online endpoint. Absent → a fixed fleet sized by Instances.

object (model.InferenceServerSchedule)
object

ScheduledBatch is the stepper config a batch-mode server reuses on each scheduled fire (rolling window). The schedule lives in Schedule.

space
required
string
tag
string
topology
string
Enum: "split" "fused"

Topology selects the online engine layout: "split" (default; empty = split) runs the embedding + backbone pair, "fused" runs one fused engine. Fused is online only — the service rejects it for a batch-only server.

training_id
string
weight_load
string
Enum: "standard" "legacy"

WeightLoad selects the engine checkpoint-head load path: "standard" (default) or "legacy" (pre-refactor checkpoints, older head layout). Absent → standard. Engine-only: it reaches both GPU engine roles on every deploy type and never the context store.

Responses

Request samples

Content type
application/json
{
  • "architecture": "string",
  • "auto_batch_config": {
    },
  • "checkpoint_id": "string",
  • "compile": true,
  • "compile_mode": "regional",
  • "connectors": {
    },
  • "cortex_image": "string",
  • "data_model_id": "string",
  • "datavolume_name": "string",
  • "datavolume_subpath": "string",
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": {
    },
  • "inference_type": "batch",
  • "inference_version": "string",
  • "instances": 0,
  • "mode": "online",
  • "model_path": "string",
  • "model_source": "checkpoint",
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "string",
  • "tag": "string",
  • "topology": "split",
  • "training_id": "string",
  • "weight_load": "standard"
}

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "auto_batch_config": {
    },
  • "checkpoint": 1,
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "compile": false,
  • "compile_mode": "example",
  • "connectors": {
    },
  • "context_config": {
    },
  • "cortex_image": "registry.example.com/image:tag",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "datavolume_name": "shared-datasets",
  • "datavolume_subpath": "transactions/2026-01",
  • "desired_endpoint_port": 1,
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": { },
  • "epoch": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_type": "example",
  • "inference_version": "1.0.0",
  • "instances": 1,
  • "job_state_reasons": { },
  • "job_states": { },
  • "last_deployed_at": "2026-01-15T10:30:00Z",
  • "mode": "example",
  • "model_dir": "/datasets/transactions",
  • "model_path": "/datasets/transactions",
  • "model_source": "example",
  • "monitoring_settings": {
    },
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tag": "example",
  • "topology": "example",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "weight_load": "example"
}

/v1/spaces/{spaceId}/inference-servers/{id}

path Parameters
id
required
string

Inference server ID

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}" \
  -H "x-api-key: $API_KEY"

/v1/spaces/{spaceId}/inference-servers/{id}

path Parameters
id
required
string

Inference server ID

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}" \
  -H "x-api-key: $API_KEY"

Patch inference server (lifecycle status)

path Parameters
id
required
string

Inference server ID

Request Body schema: application/json
required

Body (status canceled = undeploy; running = activate, may persist as awaiting_inference when instances is 0)

status
required
string
Enum: "canceled" "running"

canceled: soft undeploy. running: activate (stored as running or awaiting_inference when instances is 0).

Responses

Request samples

Content type
application/json
{
  • "status": "canceled"
}

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "auto_batch_config": {
    },
  • "checkpoint": 1,
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "compile": false,
  • "compile_mode": "example",
  • "connectors": {
    },
  • "context_config": {
    },
  • "cortex_image": "registry.example.com/image:tag",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "datavolume_name": "shared-datasets",
  • "datavolume_subpath": "transactions/2026-01",
  • "desired_endpoint_port": 1,
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": { },
  • "epoch": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_type": "example",
  • "inference_version": "1.0.0",
  • "instances": 1,
  • "job_state_reasons": { },
  • "job_states": { },
  • "last_deployed_at": "2026-01-15T10:30:00Z",
  • "mode": "example",
  • "model_dir": "/datasets/transactions",
  • "model_path": "/datasets/transactions",
  • "model_source": "example",
  • "monitoring_settings": {
    },
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tag": "example",
  • "topology": "example",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "weight_load": "example"
}

/v1/spaces/{spaceId}/inference-servers/{id}

path Parameters
id
required
string

Inference server ID

Request Body schema: application/json
required

Body

architecture
string <= 128 characters

Architecture names which platform architecture the model was trained under, for a path/datavolume deploy that has NO checkpoint lineage. It supplies the inference config (rust image + tunables) AND the cortex image the GPU engines run in (always multi-version — the training cortex, never cortex-infer-gpu) — the provenance a lineage-free deploy otherwise lacks. Empty → the platform's current default architecture (the most recent cortex). Ignored for a checkpoint source (which resolves the architecture from the checkpoint's training lineage).

object

AutoBatchConfig is the batch-mode automation intent (input source + schedule

  • no-new-files behavior). Previously the decoder dropped it.
checkpoint_id
string
compile
boolean

Compile is the torch.compile override for every engine role (embedding, backbone, fused). Omitted compiles; an explicit false runs the engines eager. Engine-only — it never reaches the context store.

compile_mode
string
Enum: "regional" "max-autotune"

CompileMode is the torch.compile mode the FUSED engine uses when Compile is on: "regional" (the default) or "max-autotune". "whole" is intentionally not offered (documented broken). The embedding and backbone engines always compile regionally.

object

Connectors carries the server's optional input data integrations. It is no longer required — the output destination moved to the batch run — so a deploy that sends none (or only inputs) is accepted.

cortex_image
string <= 512 characters

CortexImage optionally overrides the GPU/training cortex image the engines run in (the multi-version main container) — a full image ref typed by hand for a path/datavolume deploy. Empty → the architecture's image. Ignored for a checkpoint source (which resolves the image from its training lineage).

data_model_id
string

The lineage IDs are required only for the default checkpoint source; the lineage-free sources (path, datavolume) omit them. gin's required_unless takes a single value, so the "checkpoint source requires lineage" rule is enforced in the service Create instead (same rejection, better message) — the binding leaves them optional.

datavolume_name
string

DataVolumeName is the neocore DataVolume to serve the model from, required when model_source is "datavolume". DataVolumeSubpath is the optional dir under its mount the model lives in (empty = the mount root).

datavolume_subpath
string
object

EmbeddingQuant is the optional TurboQuant embedding-quantization knob. Absent → no quantization (emitted configs are byte-identical to before). Only online deploys carry it (folded into the model fingerprint across the engines + context store + server). Scheme/Bits/Seed/Rounds default server-side when omitted; Enabled defaults false.

object

Endpoint optionally fixes the online server's client-facing external port at deploy (online only): a specific port or a range to draw one from. Absent → neocore auto-allocates. Persisted as the server's desired port and pinned when the online HTTP server is brought up.

object

EngineScaling is the optional autoscaling config for the GPU engine tier (embedding + backbone). Absent → fixed single-replica engine jobs.

object

EngineYaml carries optional per-role user-edited engine config documents — the advanced "edit engine YAML" deploy mode — keyed by engine role: "embedding"/"backbone" for a split server, "fused" for a fused server. For each role present, the engine job mounts the user's document with the platform-managed engine fields (model dir, mode, embed_dtype, transport wiring, embedding_quant) deep-merged OVER it, so the operator can't break serving. Roles not present (or an empty string / absent map) fall back to the field-derived config — byte-identical to a deploy made before this knob existed. Malformed YAML → 400. Unknown role keys → 400.

inference_type
required
string
Enum: "batch" "online"
inference_version
string <= 128 characters

InferenceVersion overrides the cortex-infer image tag (tag only, e.g. "v0.0.8"); empty = the architecture's tag (latest). Validated tag-only in the service.

instances
integer
mode
string
Enum: "online" "batch" "hybrid"

Mode is the deploy intent: "online" (serves /infer), "hybrid" (serves /infer AND accepts batch runs through its engines, which default to the engine's batch mode — the portal's "Batch" deploy) or "batch" (accepts batch runs, no endpoint). It must agree with inference_type (online and hybrid are online types), and omitted derives from it.

model_path
string

ModelPath is the operator-supplied absolute model dir, required when model_source is "path". Must be under a shared volume (/shared or /mnt/fss).

model_source
string
Enum: "checkpoint" "path" "datavolume"

ModelSource selects where the served model dir comes from: "checkpoint" (the default; empty is treated as checkpoint) resolves the data-model / training / checkpoint lineage, "path" serves ModelPath directly (no lineage), or "datavolume" serves a dir under a neocore DataVolume's mount (no lineage).

object

Scaling is the optional autoscaling config for an online endpoint. Absent → a fixed fleet sized by Instances.

object (model.InferenceServerSchedule)
object

ScheduledBatch is the stepper config a batch-mode server reuses on each scheduled fire (rolling window). The schedule lives in Schedule.

space
required
string
tag
string
topology
string
Enum: "split" "fused"

Topology selects the online engine layout: "split" (default; empty = split) runs the embedding + backbone pair, "fused" runs one fused engine. Fused is online only — the service rejects it for a batch-only server.

training_id
string
weight_load
string
Enum: "standard" "legacy"

WeightLoad selects the engine checkpoint-head load path: "standard" (default) or "legacy" (pre-refactor checkpoints, older head layout). Absent → standard. Engine-only: it reaches both GPU engine roles on every deploy type and never the context store.

Request samples

Content type
application/json
{
  • "architecture": "string",
  • "auto_batch_config": {
    },
  • "checkpoint_id": "string",
  • "compile": true,
  • "compile_mode": "regional",
  • "connectors": {
    },
  • "cortex_image": "string",
  • "data_model_id": "string",
  • "datavolume_name": "string",
  • "datavolume_subpath": "string",
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": {
    },
  • "inference_type": "batch",
  • "inference_version": "string",
  • "instances": 0,
  • "mode": "online",
  • "model_path": "string",
  • "model_source": "checkpoint",
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "string",
  • "tag": "string",
  • "topology": "split",
  • "training_id": "string",
  • "weight_load": "standard"
}

Configure the context store

Persist how much cached context the online endpoint keeps per user.

path Parameters
id
required
string

Inference server ID

Request Body schema: application/json
required

Context configuration

enabled
boolean
lookback_window
string
max_len
integer
min_context
integer
mismatch_strategy
string

Responses

Request samples

Content type
application/json
{
  • "enabled": true,
  • "lookback_window": "string",
  • "max_len": 0,
  • "min_context": 0,
  • "mismatch_strategy": "string"
}

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "auto_batch_config": {
    },
  • "checkpoint": 1,
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "compile": false,
  • "compile_mode": "example",
  • "connectors": {
    },
  • "context_config": {
    },
  • "cortex_image": "registry.example.com/image:tag",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "datavolume_name": "shared-datasets",
  • "datavolume_subpath": "transactions/2026-01",
  • "desired_endpoint_port": 1,
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": { },
  • "epoch": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_type": "example",
  • "inference_version": "1.0.0",
  • "instances": 1,
  • "job_state_reasons": { },
  • "job_states": { },
  • "last_deployed_at": "2026-01-15T10:30:00Z",
  • "mode": "example",
  • "model_dir": "/datasets/transactions",
  • "model_path": "/datasets/transactions",
  • "model_source": "example",
  • "monitoring_settings": {
    },
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tag": "example",
  • "topology": "example",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "weight_load": "example"
}

Get decision thresholds

The score cut-offs the server applies when turning a prediction into a decision.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/decision-thresholds" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "targets": [
    ]
}

Current engine config YAML(s) for a provisioned server

Renders each engine role's current effective engine config for an already-deployed server (folding in any persisted per-role override), with the platform-managed fields shown as placeholders. Pre-fills the reconfigure editor. Creates nothing.

path Parameters
spaceId
required
string

Space id

id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/engine-config" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "configs": { }
}

Reconfigure a provisioned server's engine YAML

Applies per-role engine-config overrides to an already-provisioned server and recreates ONLY the reconfigured engine role(s) with the new config — a brief serving interruption on the affected tier. Managed fields are re-injected; unknown role / malformed YAML → 400.

path Parameters
spaceId
required
string

Space id

id
required
string

Inference server ID

Request Body schema: application/json
required

Per-role engine YAML

object
property name*
additional property
string

Responses

Request samples

Content type
application/json
{
  • "engine_yaml": {
    }
}

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "auto_batch_config": {
    },
  • "checkpoint": 1,
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "compile": false,
  • "compile_mode": "example",
  • "connectors": {
    },
  • "context_config": {
    },
  • "cortex_image": "registry.example.com/image:tag",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "datavolume_name": "shared-datasets",
  • "datavolume_subpath": "transactions/2026-01",
  • "desired_endpoint_port": 1,
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": { },
  • "epoch": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_type": "example",
  • "inference_version": "1.0.0",
  • "instances": 1,
  • "job_state_reasons": { },
  • "job_states": { },
  • "last_deployed_at": "2026-01-15T10:30:00Z",
  • "mode": "example",
  • "model_dir": "/datasets/transactions",
  • "model_path": "/datasets/transactions",
  • "model_source": "example",
  • "monitoring_settings": {
    },
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tag": "example",
  • "topology": "example",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "weight_load": "example"
}

Manually scale a role's replica bounds

Bump one role's (embedding | backbone | server) ScalingGroup min/max replica bounds on demand. Floored to min >= 1, max >= min.

path Parameters
id
required
string

Inference server ID

role
required
string

Role (embedding | backbone | server)

Request Body schema: application/json
required

New bounds

max
integer
min
integer

Responses

Request samples

Content type
application/json
{
  • "max": 0,
  • "min": 0
}

Response samples

Content type
application/json
{
  • "max": 4,
  • "min": 1,
  • "role": "example"
}

Get the served model

The checkpoint the server serves, its parameter counts, and the input and target views a caller must fill.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/model" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "info": {
    },
  • "input_views": [
    ],
  • "target_views": [
    ]
}

Get the served model layout

The model's tensor/shard layout as published by the engine, forwarded verbatim.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/model/layout" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{ }

Configure monitoring settings

Set the drift and quality monitoring the server runs against its own traffic.

path Parameters
id
required
string

Inference server ID

Request Body schema: application/json
required

Monitoring settings

critical_ks_d
required
number <= 1
object (request.ConfigureDecisionThresholdRequest)
warn_ks_d
required
number <= 1

Responses

Request samples

Content type
application/json
{
  • "critical_ks_d": 1,
  • "decision_threshold": {
    },
  • "warn_ks_d": 1
}

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "auto_batch_config": {
    },
  • "checkpoint": 1,
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "compile": false,
  • "compile_mode": "example",
  • "connectors": {
    },
  • "context_config": {
    },
  • "cortex_image": "registry.example.com/image:tag",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "datavolume_name": "shared-datasets",
  • "datavolume_subpath": "transactions/2026-01",
  • "desired_endpoint_port": 1,
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": { },
  • "epoch": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_type": "example",
  • "inference_version": "1.0.0",
  • "instances": 1,
  • "job_state_reasons": { },
  • "job_states": { },
  • "last_deployed_at": "2026-01-15T10:30:00Z",
  • "mode": "example",
  • "model_dir": "/datasets/transactions",
  • "model_path": "/datasets/transactions",
  • "model_source": "example",
  • "monitoring_settings": {
    },
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tag": "example",
  • "topology": "example",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "weight_load": "example"
}

Start the online server

Bring up the online (synchronous) inference endpoint. Accepted immediately; the server reports READY through its status.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/online-server" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "auto_batch_config": {
    },
  • "checkpoint": 1,
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "compile": false,
  • "compile_mode": "example",
  • "connectors": {
    },
  • "context_config": {
    },
  • "cortex_image": "registry.example.com/image:tag",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "datavolume_name": "shared-datasets",
  • "datavolume_subpath": "transactions/2026-01",
  • "desired_endpoint_port": 1,
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": { },
  • "epoch": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_type": "example",
  • "inference_version": "1.0.0",
  • "instances": 1,
  • "job_state_reasons": { },
  • "job_states": { },
  • "last_deployed_at": "2026-01-15T10:30:00Z",
  • "mode": "example",
  • "model_dir": "/datasets/transactions",
  • "model_path": "/datasets/transactions",
  • "model_source": "example",
  • "monitoring_settings": {
    },
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tag": "example",
  • "topology": "example",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "weight_load": "example"
}

Get online server connection details

The URL and credentials a client needs to call the online endpoint.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/online-server/connection" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "health_check": {
    },
  • "http_endpoint": {
    },
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "job_name": "churn-propensity-v3",
  • "leader_task": "example",
  • "metrics_endpoint": {
    },
  • "node_ip": "example",
  • "node_name": "churn-propensity-v3"
}

Get engine replica state

Per-role (embedding | backbone | server) replica counts and readiness, forwarded from the scaling groups.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/online-server/replicas" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{ }

Stop the online server

Tear the online endpoint down and release its engine replicas.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/online-server/stop" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "auto_batch_config": {
    },
  • "checkpoint": 1,
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "compile": false,
  • "compile_mode": "example",
  • "connectors": {
    },
  • "context_config": {
    },
  • "cortex_image": "registry.example.com/image:tag",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "datavolume_name": "shared-datasets",
  • "datavolume_subpath": "transactions/2026-01",
  • "desired_endpoint_port": 1,
  • "embedding_quant": {
    },
  • "endpoint": {
    },
  • "engine_scaling": {
    },
  • "engine_yaml": { },
  • "epoch": 1,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_type": "example",
  • "inference_version": "1.0.0",
  • "instances": 1,
  • "job_state_reasons": { },
  • "job_states": { },
  • "last_deployed_at": "2026-01-15T10:30:00Z",
  • "mode": "example",
  • "model_dir": "/datasets/transactions",
  • "model_path": "/datasets/transactions",
  • "model_source": "example",
  • "monitoring_settings": {
    },
  • "scaling": {
    },
  • "schedule": {
    },
  • "scheduled_batch": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tag": "example",
  • "topology": "example",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z",
  • "weight_load": "example"
}

Send a test request to the online server

Run one inference against the live endpoint and return the raw response, for smoke-testing a deploy.

path Parameters
id
required
string

Inference server ID

Request Body schema: application/json
required

Test inference payload

body
required
Array of integers
path
required
string

Responses

Request samples

Content type
application/json
{
  • "body": [
    ],
  • "path": "string"
}

Response samples

Content type
application/json
{
  • "body": [
    ],
  • "body_text": "example",
  • "elapsed_ms": 1,
  • "status": 1,
  • "truncated": false
}

Resume (redeploy) a canceled or failed inference server

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/resume" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
No sample

context-store

Clear the server's context store

Destructive: wipes every cached context for the server.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{ }

List the server's context-store builds

path Parameters
id
required
string

Inference server ID

query Parameters
limit
integer

Max builds per page (default 50, max 100)

after
string

Cursor: the last build id from the previous page

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store/builds" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Start a context-store build

Spawns one embedding-cache build job per dataset to populate the server's context store.

path Parameters
id
required
string

Inference server ID

Request Body schema: application/json
required

Build configuration

Array of objects (request.ContextStoreBuildDatasetItem)
Array of objects (request.ContextStoreBuildLocalDatasetItem)
shards
integer [ 1 .. 64 ]

Shards is how many data-parallel builder jobs to launch. Each shard owns a disjoint slice of the store's buckets (worker i of N via --bucket-shard i/N), so N builders write non-overlapping clients into the same store daemon. 0/omitted = 1 = the single-job build (unchanged). The store is shard-disjoint by client, so any N is safe; there is no power-of-two constraint.

Responses

Request samples

Content type
application/json
{
  • "datasets": [
    ],
  • "datasets_local": [
    ],
  • "shards": 1
}

Response samples

Content type
application/json
{
  • "build_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "datasets": [
    ],
  • "failed_clients": 1,
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "progress": {
    },
  • "retried_from_build_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "shards": [
    ],
  • "status": "PENDING",
  • "stopped_at": "2026-01-15T10:30:00Z"
}

Delete a context-store build

Stops the build (deletes any of its neocore jobs still around) and removes its record. Clients already written to the store stay there — use the store delete to wipe them.

path Parameters
id
required
string

Inference server ID

buildId
required
string

Build ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store/builds/{buildId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
No sample

Retry a build's failed clients

Creates a NEW build that re-embeds only the clients the source build dead-lettered (skipped after backoff-retry), one shard job per source shard that had failures. The source build is left untouched.

path Parameters
id
required
string

Inference server ID

buildId
required
string

Source build ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store/builds/{buildId}/retry-failed-clients" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "build_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "datasets": [
    ],
  • "failed_clients": 1,
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "progress": {
    },
  • "retried_from_build_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "shards": [
    ],
  • "status": "PENDING",
  • "stopped_at": "2026-01-15T10:30:00Z"
}

Stop a context-store build

Deletes the build's neocore job(s), so a running build stops embedding. The build record stays and lists as Canceled. Clients already written to the store stay there.

path Parameters
id
required
string

Inference server ID

buildId
required
string

Build ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store/builds/{buildId}/stop" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "build_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "datasets": [
    ],
  • "failed_clients": 1,
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "progress": {
    },
  • "retried_from_build_id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "shards": [
    ],
  • "status": "PENDING",
  • "stopped_at": "2026-01-15T10:30:00Z"
}

Context-store serving metrics

Request/error rate, get/append p99 latency, hit rate and RocksDB size, compaction and stall history for the server's context-store daemon over a rolling window. Series without samples are empty arrays.

path Parameters
id
required
string

Inference server ID

query Parameters
window
string
Default: "1h"

Window as a Go duration (e.g. 1h), capped at 168h

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store/metrics" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "current": {
    },
  • "series": {
    },
  • "step": "example",
  • "window": "example"
}

Context-store occupancy

Proxies the context-store daemon's stats verbatim.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store/occupancy" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{ }

List users held in the context store

Proxies the context-store daemon's user listing verbatim; the query string is forwarded as-is.

path Parameters
id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store/users" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{ }

Preview one user's cached context

Proxies the context-store daemon's per-user context verbatim.

path Parameters
id
required
string

Inference server ID

userId
required
string

User ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/context-store/users/{userId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{ }

drift

Drift heatmap for an inference server

path Parameters
spaceId
required
string

Space ID

id
required
string

Inference server ID

query Parameters
granularity
string

Bucket granularity

start
string

Range start (RFC3339)

end
string

Range end (RFC3339)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/drift" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "baseline": { },
  • "granularity": "example",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "targets": { }
}

Baseline drift report of an inference server

path Parameters
spaceId
required
string

Space ID

id
required
string

Inference server ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/drift/baseline/report" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "mode": "example",
  • "run_id": "bif_1a2b3c4d5e6f708192a3b4c5",
  • "run_output_dir": "/datasets/transactions",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z"
}

List a server's drift reports

path Parameters
spaceId
required
string

Space ID

id
required
string

Inference server ID

query Parameters
limit
integer

Page size

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/drift/reports" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
[
  • {
    }
]

Drift report of one batch inference run

path Parameters
spaceId
required
string

Space ID

id
required
string

Inference server ID

runId
required
string

Batch inference run ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/drift/runs/{runId}/report" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "checkpoint_id": "che_1a2b3c4d5e6f708192a3b4c5",
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "mode": "example",
  • "run_id": "bif_1a2b3c4d5e6f708192a3b4c5",
  • "run_output_dir": "/datasets/transactions",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "training_id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "updated_at": "2026-01-15T10:30:00Z"
}

Re-run drift analysis for a batch inference run

path Parameters
spaceId
required
string

Space ID

id
required
string

Inference server ID

runId
required
string

Batch inference run ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/drift/runs/{runId}/retry" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

Drift detail for one target

path Parameters
spaceId
required
string

Space ID

id
required
string

Inference server ID

target
required
string

Target name

query Parameters
column
string

Column filter

class
string

Class filter

granularity
string

Bucket granularity

start
string

Range start (RFC3339)

end
string

Range end (RFC3339)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/drift/targets/{target}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "baseline": {
    },
  • "class": "example",
  • "column": "event_ts",
  • "periods": [
    ],
  • "target": "example"
}

Drift detail for one target period

path Parameters
spaceId
required
string

Space ID

id
required
string

Inference server ID

target
required
string

Target name

periodId
required
string

Drift period ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/drift/targets/{target}/periods/{periodId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "baseline_full": {
    },
  • "profile_period": {
    },
  • "target": "example"
}

stress-runs

List a server's stress runs

path Parameters
id
required
string

Inference server ID

query Parameters
limit
integer

Page size

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/inference-servers/{id}/stress-runs" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create a stress run for a server

path Parameters
id
required
string

Inference server ID

Request Body schema: application/json
required

Stress run configuration

object (request.CreateStressRunBreaker)
events_per_request
integer
required
object
required
Array of objects (request.CreateStressRunStage) non-empty
timeout_ms
integer
unique_field
string
warmup_s
integer

Responses

Request samples

Content type
application/json
{
  • "breaker": {
    },
  • "events_per_request": 0,
  • "payload": {
    },
  • "stages": [
    ],
  • "timeout_ms": 0,
  • "unique_field": "string",
  • "warmup_s": 0
}

Response samples

Content type
application/json
{
  • "config": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "finished_at": "2026-01-15T10:30:00Z",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "report": { },
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message"
}

Get a stress run

path Parameters
id
required
string

Stress run ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/stress-runs/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "config": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "finished_at": "2026-01-15T10:30:00Z",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "report": { },
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message"
}

Cancel a stress run

path Parameters
id
required
string

Stress run ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/stress-runs/{id}/cancel" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "config": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": "example",
  • "finished_at": "2026-01-15T10:30:00Z",
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "inference_server_id": "inf_1a2b3c4d5e6f708192a3b4c5",
  • "report": { },
  • "started_at": "2026-01-15T10:30:00Z",
  • "status": "PENDING",
  • "status_reason": "Example message"
}

Recent log lines of a stress run

Best-effort tail of the stress job's logs; empty while the job runs healthy.

path Parameters
id
required
string

Stress run ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/stress-runs/{id}/logs" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{ }

leaderboards

List leaderboards

Retrieve a paginated list of checkpoints grouped with their metrics for leaderboard display

query Parameters
limit
integer
Default: 10

Limit

after
string

Cursor for pagination (checkpoint ID of last item, required with after_metric_value)

model_id
string

Filter by model/checkpoint ID

benchmarks
Array of strings

Filter by benchmark IDs (can be multiple)

trainings
Array of strings

Filter by training IDs (can be multiple)

start_date
string

Filter by start date (RFC3339 format, e.g., 2024-01-01T00:00:00Z)

end_date
string

Filter by end date (RFC3339 format, e.g., 2024-12-31T23:59:59Z)

order_by_metric.metric_name
string

Order by this metric name (requires dataset_name and target_name)

order_by_metric.dataset_name
string

Dataset name for metric ordering (required when ordering by metric)

order_by_metric.target_name
string

Target name for metric ordering (required when ordering by metric)

order_by_metric.after_metric_value
number

Metric value of last item for cursor pagination (requires after param)

order_by_metric.direction
string
Default: "desc"

Order direction: asc or desc

name
string

Filter by checkpoint name

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/leaderboards" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "has_more": false
}

model-designs

List design models

query Parameters
kind
string

model_input or model_output

status
string

draft, published or archived

name
string

name substring filter

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-designs" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create design model

Create a design model (input or output) with its content, in

Request Body schema: application/json
required

Create body

Array of objects (model.ModelDesignDataset)
description
string <= 300 characters
Array of objects (model.ModelDesignColumnRef)
kind
required
string
Enum: "model_input" "model_output"
object (model.ModelDesignMetrics)
name
required
string <= 100 characters
publish
boolean
Array of objects (model.ModelDesignTask)
object (model.ModelDesignTimeRanges)

Responses

Request samples

Content type
application/json
{
  • "datasets": [
    ],
  • "description": "string",
  • "global_tokens": [
    ],
  • "kind": "model_input",
  • "metrics": {
    },
  • "name": "string",
  • "publish": true,
  • "tasks": [
    ],
  • "time_ranges": {
    }
}

Response samples

Content type
application/json
{
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "datasets": [
    ],
  • "description": "Scores the active customer base every morning.",
  • "global_tokens": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "model_input",
  • "metrics": {
    },
  • "name": "churn-propensity-v3",
  • "published_at": "2026-01-15T10:30:00Z",
  • "status": "draft",
  • "tasks": [
    ],
  • "time_ranges": {
    },
  • "updated_at": "2026-01-15T10:30:00Z",
  • "used_in_training": false
}

Delete a design model

Soft-deletes the design (stamps deleted_at). The row is kept

path Parameters
id
required
string

Design model ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-designs/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "error": "example"
}

Get design model

path Parameters
id
required
string

Design model ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-designs/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "datasets": [
    ],
  • "description": "Scores the active customer base every morning.",
  • "global_tokens": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "model_input",
  • "metrics": {
    },
  • "name": "churn-propensity-v3",
  • "published_at": "2026-01-15T10:30:00Z",
  • "status": "draft",
  • "tasks": [
    ],
  • "time_ranges": {
    },
  • "updated_at": "2026-01-15T10:30:00Z",
  • "used_in_training": false
}

Archive a design model

Marks the design as archived. Archived designs remain in the

path Parameters
id
required
string

Design model ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-designs/{id}/archive" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "datasets": [
    ],
  • "description": "Scores the active customer base every morning.",
  • "global_tokens": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "model_input",
  • "metrics": {
    },
  • "name": "churn-propensity-v3",
  • "published_at": "2026-01-15T10:30:00Z",
  • "status": "draft",
  • "tasks": [
    ],
  • "time_ranges": {
    },
  • "updated_at": "2026-01-15T10:30:00Z",
  • "used_in_training": false
}

Publish a design model

Stores the content and flips a draft design to published,

path Parameters
id
required
string

Design model ID

Request Body schema: application/json
required

Design content

Array of objects (model.ModelDesignDataset)
Array of objects (model.ModelDesignColumnRef)
object (model.ModelDesignMetrics)
Array of objects (model.ModelDesignTask)
object (model.ModelDesignTimeRanges)

Responses

Request samples

Content type
application/json
{
  • "datasets": [
    ],
  • "global_tokens": [
    ],
  • "metrics": {
    },
  • "tasks": [
    ],
  • "time_ranges": {
    }
}

Response samples

Content type
application/json
{
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "datasets": [
    ],
  • "description": "Scores the active customer base every morning.",
  • "global_tokens": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "model_input",
  • "metrics": {
    },
  • "name": "churn-propensity-v3",
  • "published_at": "2026-01-15T10:30:00Z",
  • "status": "draft",
  • "tasks": [
    ],
  • "time_ranges": {
    },
  • "updated_at": "2026-01-15T10:30:00Z",
  • "used_in_training": false
}

Unarchive a design model

Clears the archived flag. The design comes back with the

path Parameters
id
required
string

Design model ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-designs/{id}/unarchive" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "archived_at": "2026-01-15T10:30:00Z",
  • "created_at": "2026-01-15T10:30:00Z",
  • "created_by": {
    },
  • "datasets": [
    ],
  • "description": "Scores the active customer base every morning.",
  • "global_tokens": [
    ],
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "model_input",
  • "metrics": {
    },
  • "name": "churn-propensity-v3",
  • "published_at": "2026-01-15T10:30:00Z",
  • "status": "draft",
  • "tasks": [
    ],
  • "time_ranges": {
    },
  • "updated_at": "2026-01-15T10:30:00Z",
  • "used_in_training": false
}

model-endpoints

List model endpoints

path Parameters
spaceId
required
string

Space ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-endpoints" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
[
  • {
    }
]

Deploy a model endpoint

Deploys one configuration (weights format + profile) of a cataloged model. The chosen configuration is RE-VALIDATED against current cluster capacity before anything is created, so a plan that has gone stale is refused with 409 rather than deployed into a queue.

path Parameters
spaceId
required
string

Space ID

Request Body schema: application/json
required

Endpoint configuration

kv_offload
string

KVOffload is how far the cache travels: off, offloading, lmcache, mooncake. StoreTopology applies only to the modes that share a pool, and says who owns its memory.

max_context_tokens
integer

MaxContextTokens is the advertised context window. Optional (the model's own maximum applies), and not cosmetic: it shapes the cache reservation, so raising it can make an otherwise-deployable configuration stop fitting.

name
required
string

Name is the operator's label, unique within the space.

port
integer

Port fixes the client-facing port; 0 lets neocore allocate one. A fixed port is reserved before any GPU is claimed, so an unavailable one fails the deploy instead of silently landing somewhere else.

profile_id
required
string
object

RoleScaling sizes the two phases of a prefill/decode deploy on their own, keyed "prefill" and "decode": both or neither, and only with that strategy. Absent, every role takes Scaling, as before. Given, Scaling bounds the router in front of them. Phases sized alike still run as units of one prefill and one decode where a pair fits a node; phases sized apart cannot be cut into units, so they run as fleets and the KV crosses the network, which needs a fast fabric. Scale-to-zero is the whole endpoint's: scaling.min and both phases' min are 0, or none is.

object (request.ModelEndpointScalingRequest)
served_model_id
string

ServedModelID or ServedModelName identifies the catalog entry; one is required.

served_model_name
string
shared_cache
boolean

SharedCache overrides whether the endpoint runs a shared cross-machine KV pool. Left unset, the platform follows the machine boundary: a fleet that can place replicas on different machines (max > 1) pools its KV so scaling out shares the prefix cache instead of siloing it. Set false to force replica-local caching (economy, or a model with a known store gap); set true to demand it (refused if the model does not support the store). A pointer so "unset" and "false" are different instructions.

spec_decoding
boolean

SpecDecoding requests the checkpoint's fused draft module. Refused when the chosen variant ships none, because the engine will not start when told to speculate with weights that cannot.

store_topology
string
strategy
string

Strategy is the parallelism family. Must be one the model declares — and one its chosen variant does not exclude, since a fused release can carry kernels its siblings lack.

variant_id
string

VariantID names the CHECKPOINT to serve. A weights format cannot identify one: two checkpoints of a model can share a precision and differ in release, publisher and draft module. WeightsFormat above stays for callers that predate variants and resolves to the model's only checkpoint at that precision.

weights_format
required
string

WeightsFormat and ProfileID are the picked cell. Both are required because a configuration is the pair — a format without a parallelism is not deployable, and defaulting either one would deploy something the operator did not choose.

weights_secret_name
string

WeightsSecretName is the external secret that unlocks gated weights. Required only when the chosen variant is gated, and only the NAME travels — the credential itself is resolved on the node and never reaches the platform.

Responses

Request samples

Content type
application/json
{
  • "kv_offload": "string",
  • "max_context_tokens": 0,
  • "name": "string",
  • "port": 0,
  • "profile_id": "string",
  • "role_scaling": {
    },
  • "scaling": {
    },
  • "served_model_id": "string",
  • "served_model_name": "string",
  • "shared_cache": true,
  • "spec_decoding": true,
  • "store_topology": "string",
  • "strategy": "string",
  • "variant_id": "string",
  • "weights_format": "string",
  • "weights_secret_name": "string"
}

Response samples

Content type
application/json
{
  • "address": {},
  • "context_pool": {
    },
  • "created_at": "2026-01-15T10:30:00Z",
  • "deployed_at": "2026-01-15T10:30:00Z",
  • "gpus_per_node": 2,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "max_context_tokens": 4,
  • "name": "churn-propensity-v3",
  • "nodes": 2,
  • "pipeline_parallel": 1,
  • "profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "role_scaling": { },
  • "roles": [
    ],
  • "scaling": {
    },
  • "served_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "served_model_name": "churn-propensity",
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tensor_parallel": 1,
  • "topology": "example",
  • "total_gpus": 8,
  • "weights_format": "example"
}

List weight staging progress

Lists the staged weight sets and their progress. A deploy that is waiting on weights is answered here: a several-hundred-gigabyte fetch takes a long time, and "preparing, 40 GB so far" is a very different answer from an endpoint that will not start.

path Parameters
spaceId
required
string

Space ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-endpoints/weight-stages" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
[
  • {
    }
]

Delete a model endpoint

Tears down the serving fleet and the endpoint address, then removes the record. Teardown is best-effort per resource: a neocore failure is logged and the record is still removed, because an endpoint nobody can delete through the API is worse than a resource to clean up.

path Parameters
spaceId
required
string

Space ID

id
required
string

Model endpoint ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-endpoints/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{ }

Get a model endpoint

path Parameters
spaceId
required
string

Space ID

id
required
string

Model endpoint ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-endpoints/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "address": {},
  • "context_pool": {
    },
  • "created_at": "2026-01-15T10:30:00Z",
  • "deployed_at": "2026-01-15T10:30:00Z",
  • "gpus_per_node": 2,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "max_context_tokens": 4,
  • "name": "churn-propensity-v3",
  • "nodes": 2,
  • "pipeline_parallel": 1,
  • "profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "role_scaling": { },
  • "roles": [
    ],
  • "scaling": {
    },
  • "served_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "served_model_name": "churn-propensity",
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tensor_parallel": 1,
  • "topology": "example",
  • "total_gpus": 8,
  • "weights_format": "example"
}

Live serving metrics for a model endpoint

path Parameters
spaceId
required
string

Space ID

id
required
string

Model endpoint ID

query Parameters
window
string

Lookback window (e.g. 15m, 1h)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-endpoints/{id}/metrics" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "e2e_avg_ms": 0.5,
  • "generation_tokens_per_sec": 0.5,
  • "kv_cache_usage": 0.5,
  • "kv_capacity_derived": false,
  • "kv_capacity_gb": 0.5,
  • "kv_transfer": {
    },
  • "kv_used_gb": 0.5,
  • "lookback_seconds": 1,
  • "now_seconds": 1,
  • "preemptions_per_sec": 0.5,
  • "prefix_hit_rate": 0.5,
  • "prompt_tokens_per_sec": 0.5,
  • "queue_wait_avg_ms": 0.5,
  • "replicas": [
    ],
  • "reporting_replicas": 1,
  • "requests_per_sec": 0.5,
  • "requests_running": 0.5,
  • "requests_started_per_sec": 0.5,
  • "requests_waiting": 0.5,
  • "roles": [
    ],
  • "series": {
    },
  • "shared_hit_rate": 0.5,
  • "step_seconds": 1,
  • "topology": "example",
  • "tpot_avg_ms": 0.5,
  • "ttft_avg_ms": 0.5,
  • "window_seconds": 1
}

Shared KV pool metrics

Live view of the endpoint's shared cross-machine KV pool: how many replicas contribute to it and how big it therefore is, plus best-effort hit rate, cache occupancy and throughput scraped from the serving replicas. Returns enabled=false for an endpoint that has no pool. The optional window (e.g. 30m, 6h) sets the range of the returned sparklines.

path Parameters
spaceId
required
string

Space ID

id
required
string

Model endpoint ID

query Parameters
window
string

Time window, e.g. 30m or 6h (default 30m)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-endpoints/{id}/pool/metrics" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "enabled": true,
  • "hit_rate": 0.5,
  • "kv_cache_usage": 0.5,
  • "pool_capacity_gb": 0.5,
  • "replicas": 1,
  • "requests_running": 0.5,
  • "requests_waiting": 0.5,
  • "segment_gb_per_replica": 0.5,
  • "series": {
    },
  • "tokens_per_sec": 0.5,
  • "tokens_saved_per_sec": 0.5,
  • "transport": "example",
  • "window_seconds": 1
}

Resize a model endpoint's fleet

Change how many replicas the endpoint holds. Converges in place: the groups are rewritten and the reconciler appends or drains members, so running replicas are not torn down. Shape (parallelism, GPUs, nodes, image) is not changeable here -- that is a redeploy.

Authorizations:
ApiKeyAuth
path Parameters
spaceId
required
string

Space ID

id
required
string

Model endpoint ID

query Parameters
role
string

Resize only this phase of a split sized per phase (prefill or decode); empty resizes the endpoint's own bounds -- every role without bounds of its own

Request Body schema: application/json
required

New fleet bounds

cooldown_seconds
integer

CooldownSeconds paces repeated scale decisions; 0 takes the platform default, which is sized to how long a replica actually takes to become ready.

max
integer
min
integer
target
number

Target is the saturation level to hold the fleet at; 0 takes the platform default.

Responses

Request samples

Content type
application/json
{
  • "cooldown_seconds": 0,
  • "max": 0,
  • "min": 0,
  • "target": 0
}

Response samples

Content type
application/json
{
  • "address": {},
  • "context_pool": {
    },
  • "created_at": "2026-01-15T10:30:00Z",
  • "deployed_at": "2026-01-15T10:30:00Z",
  • "gpus_per_node": 2,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "max_context_tokens": 4,
  • "name": "churn-propensity-v3",
  • "nodes": 2,
  • "pipeline_parallel": 1,
  • "profile_id": "dp_1a2b3c4d5e6f708192a3b4c5",
  • "role_scaling": { },
  • "roles": [
    ],
  • "scaling": {
    },
  • "served_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "served_model_name": "churn-propensity",
  • "space": "example",
  • "status": "PENDING",
  • "status_reason": "Example message",
  • "tensor_parallel": 1,
  • "topology": "example",
  • "total_gpus": 8,
  • "weights_format": "example"
}

OpenAI-compatible inference

Forwards an OpenAI-compatible request (chat completions, models, ...) to the endpoint, streaming the response through. Authentication and authorisation are the platform's; the request body and the response are passed through untouched.

path Parameters
spaceId
required
string

Space ID

id
required
string

Model endpoint ID

upstream
required
string

Upstream path, e.g. /chat/completions

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/model-endpoints/{id}/v1/{upstream}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
No sample

served-models

List servable models

Lists the served-model catalog with, per model, whether it can be deployed on this space's cluster right now. A model that cannot be served is returned WITH its reason rather than omitted.

path Parameters
spaceId
required
string

Space ID

query Parameters
family
string

Narrow to one family (deepseek, qwen, glm, gemma, nemotron)

include_disabled
boolean

Include entries an operator turned off

max_context_tokens
integer

Longest conversation to assume when deciding what fits; defaults to each model's own maximum

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/served-models" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "observed_at": "2026-01-15T10:30:00Z"
}

Declare a model in the catalog

Adds one servable model to this organisation's catalog. The built-in catalog is a RECOMMENDATION, off unless the deployment enables it — this is how a deployment says what it actually serves.

path Parameters
spaceId
required
string

Space ID

Request Body schema: application/json
required

Model

active_params_b
number
autoregressive
boolean

Autoregressive é ponteiro para distinguir "não marcado" de "marcado como falso": o default é TRUE (quase todo modelo o é), e um bool simples faria o formulário que esquece o campo prometer que um difusor não faz streaming.

capabilities
Array of strings
context_pool_supported
boolean
data_parallel
integer
display_name
required
string <= 120 characters
object
object
expert_parallel
boolean
Array of objects (request.CreateServedModelProfileRequest) <= 8 items

ExtraProfiles são as formas de rodar além da principal. Cada uma é completa -- nada é herdado dos campos planos --, porque herança obrigaria a declarar como REMOVER uma flag da principal, e é exatamente a flag de uma forma que não vale na outra que motiva este campo.

family
required
string <= 60 characters
format
required
string
Enum: "bf16" "fp16" "fp8" "nvfp4" "mxfp4" "int8" "int4" "mixed"
gpus_per_node
required
integer [ 1 .. 64 ]

A configuração de execução -- o formato que o deploy vai usar.

hidden_layers
integer
hybrid_kv_cache
boolean
image
string <= 300 characters

Image é uma imagem de container repository:tag que SUBSTITUI a matriz de arquitetura no deploy deste modelo. Opcional, e é o par natural dos engine args: quem precisa de um vLLM com patch próprio precisa das duas coisas.

kv_cache_dtype
string
max_context
integer
min_runtime_version
string

Exigências da ARQUITETURA, não preferências: sem o modo de tokenizer certo um checkpoint sem chat template carrega bem e falha toda requisição de chat, e um parser ausente faz o chip de capacidade prometer o que não se cumpre.

name
required
string <= 120 characters

Identidade. Name é como o engine endereça o modelo (e o que a API do endpoint devolve em model); DisplayName é o que a tela mostra.

node_fraction
number
nodes
required
integer [ 1 .. 16 ]
params_b
required
number

Tamanho. ParamsB e ActiveParamsB andam juntos porque num MoE o ativo prevê velocidade e o total prevê custo -- quem serve lê os dois de uma vez.

pipeline_parallel
integer
reasoning_parser
string
ref
required
string <= 300 characters
size_gb
number
tensor_parallel
required
integer [ 1 .. 64 ]
tokenizer_mode
string
tool_call_parser
string
trust_remote_code
boolean
weights_source
string
Enum: "hub" "path" "hub_cache"

Onde estão os pesos, e em que precisão.

WeightsSource decide como Ref é lido:

  • hub (default): id de repositório que o deploy BAIXA e estagia;
  • path: diretório que já tem os pesos (mount compartilhado ou /localdisk);
  • hub_cache: id de repositório que o engine resolve do cache do HF do PRÓPRIO nó, offline -- nada é baixado nem estagiado, e HF_HUB_CACHE no env diz onde a árvore está.

Lista em vez de bloco indentado de propósito: indentação vira code block em markdown, e a referência publicada renderiza esta descrição.

Responses

Request samples

Content type
application/json
{
  • "active_params_b": 0,
  • "autoregressive": true,
  • "capabilities": [
    ],
  • "context_pool_supported": true,
  • "data_parallel": 0,
  • "display_name": "string",
  • "engine_args": {
    },
  • "env": {
    },
  • "expert_parallel": true,
  • "extra_profiles": [
    ],
  • "family": "string",
  • "format": "bf16",
  • "gpus_per_node": 1,
  • "hidden_layers": 0,
  • "hybrid_kv_cache": true,
  • "image": "string",
  • "kv_cache_dtype": "string",
  • "max_context": 0,
  • "min_runtime_version": "string",
  • "name": "string",
  • "node_fraction": 0,
  • "nodes": 1,
  • "params_b": 0,
  • "pipeline_parallel": 0,
  • "reasoning_parser": "string",
  • "ref": "string",
  • "size_gb": 0,
  • "tensor_parallel": 1,
  • "tokenizer_mode": "string",
  • "tool_call_parser": "string",
  • "trust_remote_code": true,
  • "weights_source": "hub"
}

Response samples

Content type
application/json
{
  • "active_params_b": 0.5,
  • "autoregressive": false,
  • "capabilities": [
    ],
  • "context_pool_supported": false,
  • "createdAt": "example",
  • "display_name": "Churn propensity",
  • "enabled": true,
  • "family": "example",
  • "hidden_layers": 1,
  • "hybrid_kv_cache": false,
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "image": "registry.example.com/image:tag",
  • "image_key": "REDACTED",
  • "internalID": "obj_1a2b3c4d5e6f708192a3b4c5",
  • "kv_bytes_per_token": 0.5,
  • "max_context": 4,
  • "min_runtime_version": "1.0.0",
  • "modality": "text",
  • "name": "churn-propensity",
  • "params_b": 0.5,
  • "profiles": [
    ],
  • "reasoning_parser": "Example message",
  • "runtime": "vllm",
  • "source": "builtin",
  • "strategies": [
    ],
  • "tokenizer_mode": "REDACTED",
  • "tool_call_parser": "example",
  • "trust_remote_code": false,
  • "updatedAt": "example",
  • "variants": [
    ]
}

Remove a model from the catalog

Removes a declared model. A BUILT-IN recommendation is hidden instead of removed — the seed re-inserts what is missing at every boot, so a disabled row is what survives that; the response says which happened. Refused while any endpoint still serves the model.

path Parameters
spaceId
required
string

Space ID

servedModelId
required
string

Served model ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/served-models/{servedModelId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "message": "Example message",
  • "outcome": "deleted"
}

trainings

Get all trainings

Retrieve a list of training jobs with cursor pagination and optional filters

query Parameters
limit
integer
Default: 10

Page size

after
string

Cursor: last training ID from the previous page

kind
string

Filter by training kind

data_model_id
string

Filter by data model ID

status
string

Filter by job status

name
string

Filter by training name (case-insensitive substring)

start_date
string

Lower bound for created_at (RFC3339 or RFC3339Nano)

end_date
string

Upper bound for created_at (RFC3339 or RFC3339Nano)

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "count": 8,
  • "data": [
    ],
  • "has_more": false
}

Create training

Create a new training job

Request Body schema: application/json
required

Training creation request

object
architecture_id
required
string
base_checkpoint
string
data_model_id
required
string
description
string
model_input_id
string

Design-driven training: when set, the service resolves TrainingDatasets / TargetDatasets and TimeRanges from the referenced Model Design's snapshot, so the client doesn't have to duplicate that mapping.

model_output_id
string
name
required
string
recipe_preset
required
string
required
object (request.RequestedResources)
object

Schedule, when set with a start_at, defers the training: it is persisted as Scheduled and dispatched by the reconciler instead of immediately.

Array of objects (model.TargetDataset)
required
object (model.TimeRanges)
Array of objects (model.TrainingDataset)

Responses

Request samples

Content type
application/json
{
  • "advanced_fields": {
    },
  • "architecture_id": "string",
  • "base_checkpoint": "string",
  • "data_model_id": "string",
  • "description": "string",
  • "model_input_id": "string",
  • "model_output_id": "string",
  • "name": "string",
  • "recipe_preset": "string",
  • "requested_resources": {
    },
  • "schedule": {
    },
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ]
}

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "architecture_id": "arc_1a2b3c4d5e6f708192a3b4c5",
  • "base_checkpoint": "example",
  • "config": "example",
  • "config_snapshot": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "description": "Scores the active customer base every morning.",
  • "filter_dataset_ids": [
    ],
  • "gpu_count": 8,
  • "id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "model_input_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "model_output_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "recipe_preset": "example",
  • "schedule": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z"
}

Delete training

Delete a training job by ID

path Parameters
id
required
string

Training ID

Responses

Request samples 

curl -X DELETE "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "id": "obj_1a2b3c4d5e6f708192a3b4c5"
}

Get training

Retrieve a training job by ID

path Parameters
id
required
string

Training ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "architecture_id": "arc_1a2b3c4d5e6f708192a3b4c5",
  • "base_checkpoint": "example",
  • "config": "example",
  • "config_snapshot": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "description": "Scores the active customer base every morning.",
  • "filter_dataset_ids": [
    ],
  • "gpu_count": 8,
  • "id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "model_input_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "model_output_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "recipe_preset": "example",
  • "schedule": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z"
}

Update training

Update a training job by ID

path Parameters
id
required
string

Training ID

Request Body schema: application/json
required

Training update request

architecture
string
benchmark_ids
Array of strings
configuration
object
object (request.UpdateConnectorTraining)
name
string

Responses

Request samples

Content type
application/json
{
  • "architecture": "string",
  • "benchmark_ids": [
    ],
  • "configuration": { },
  • "connector": {
    },
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "architecture_id": "arc_1a2b3c4d5e6f708192a3b4c5",
  • "base_checkpoint": "example",
  • "config": "example",
  • "config_snapshot": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "description": "Scores the active customer base every morning.",
  • "filter_dataset_ids": [
    ],
  • "gpu_count": 8,
  • "id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "model_input_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "model_output_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "recipe_preset": "example",
  • "schedule": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z"
}

Cancel training

Cancel a training job by ID (stops the job but preserves the training record)

path Parameters
id
required
string

Training ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}/cancel" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "architecture_id": "arc_1a2b3c4d5e6f708192a3b4c5",
  • "base_checkpoint": "example",
  • "config": "example",
  • "config_snapshot": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "description": "Scores the active customer base every morning.",
  • "filter_dataset_ids": [
    ],
  • "gpu_count": 8,
  • "id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "model_input_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "model_output_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "recipe_preset": "example",
  • "schedule": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z"
}

Get logs

Retrieve logs for a training job by ID

path Parameters
id
required
string

Training ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}/logs" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "created_at": "2026-01-15T10:30:00Z",
  • "id": "log_1a2b3c4d5e6f708192a3b4c5",
  • "job_id": "log_1a2b3c4d5e6f708192a3b4c5",
  • "text": "example"
}

Download logs as TXT

Download all logs for a training job as a plain text file

path Parameters
id
required
string

Training ID

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}/logs/download" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
No sample

Get metrics

Retrieve metrics for a training job by ID. When max_points is set and the series is longer, it is downsampled (LTTB) to about that many points; checkpoint points are always kept.

path Parameters
id
required
string

Training ID

query Parameters
type
string

Metric type filter (TRAIN, CHECKPOINT_LOSS, CHECKPOINT_VALIDATION, BENCHMARK)

max_points
integer

Max points to return; omit or <= 0 to return every point

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}/metrics" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "benchmark": "example",
  • "checkpoint": "example",
  • "checkpoint_name": "churn-propensity-v3-step-4000",
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model": "example",
  • "dataset": "example",
  • "dataset_name": "transactions-daily",
  • "epoch": 1,
  • "id": "met_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "step": 1,
  • "target": "example",
  • "training": "example",
  • "training_name": "churn-propensity-v3",
  • "type": "BENCHMARK",
  • "values": { }
}

Pause training

Pause a running training: the neocore job is deleted but checkpoints persist, so the training can be resumed later

path Parameters
id
required
string

Training ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}/pause" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "architecture_id": "arc_1a2b3c4d5e6f708192a3b4c5",
  • "base_checkpoint": "example",
  • "config": "example",
  • "config_snapshot": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "description": "Scores the active customer base every morning.",
  • "filter_dataset_ids": [
    ],
  • "gpu_count": 8,
  • "id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "model_input_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "model_output_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "recipe_preset": "example",
  • "schedule": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z"
}

Resume training

Resume a paused or failed training from its last periodic checkpoint by re-creating the neocore job. A failed run's checkpoint integrity isn't guaranteed, since the job didn't shut down cleanly.

path Parameters
id
required
string

Training ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}/resume" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "architecture_id": "arc_1a2b3c4d5e6f708192a3b4c5",
  • "base_checkpoint": "example",
  • "config": "example",
  • "config_snapshot": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "description": "Scores the active customer base every morning.",
  • "filter_dataset_ids": [
    ],
  • "gpu_count": 8,
  • "id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "model_input_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "model_output_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "recipe_preset": "example",
  • "schedule": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z"
}

Update a scheduled training's start time

Replace the deferred start time of a Scheduled (not yet started) training

path Parameters
id
required
string

Training ID

Request Body schema: application/json
required

New schedule

required
object (model.TrainingSchedule)
start_at
string
timezone
string

Responses

Request samples

Content type
application/json
{
  • "schedule": {
    }
}

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "architecture_id": "arc_1a2b3c4d5e6f708192a3b4c5",
  • "base_checkpoint": "example",
  • "config": "example",
  • "config_snapshot": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "description": "Scores the active customer base every morning.",
  • "filter_dataset_ids": [
    ],
  • "gpu_count": 8,
  • "id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "model_input_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "model_output_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "recipe_preset": "example",
  • "schedule": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z"
}

Start a scheduled training now

Dispatch a Scheduled training immediately instead of waiting for its start time

path Parameters
id
required
string

Training ID

Responses

Request samples 

curl -X POST "https://tenant.api.neospace.ai/v1/spaces/{spaceId}/trainings/{id}/start" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "architecture": "example",
  • "architecture_id": "arc_1a2b3c4d5e6f708192a3b4c5",
  • "base_checkpoint": "example",
  • "config": "example",
  • "config_snapshot": { },
  • "created_at": "2026-01-15T10:30:00Z",
  • "data_model_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "description": "Scores the active customer base every morning.",
  • "filter_dataset_ids": [
    ],
  • "gpu_count": 8,
  • "id": "tra_1a2b3c4d5e6f708192a3b4c5",
  • "kind": "PRETRAIN",
  • "model_input_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "model_output_id": "dm_1a2b3c4d5e6f708192a3b4c5",
  • "name": "churn-propensity-v3",
  • "recipe_preset": "example",
  • "schedule": {
    },
  • "space": "example",
  • "status": "PENDING",
  • "target_datasets": [
    ],
  • "time_ranges": {
    },
  • "training_datasets": [
    ],
  • "updated_at": "2026-01-15T10:30:00Z"
}

usage

Fleet usage

How long each node spent in each cluster over a period, and what its GPUs did there. The period is read as [start, end), in UTC instants; an end in the future is read up to now.

Usage comes from the hourly rollup for every hour it has written and is read live for the rest — normally the last hour or two, which coverage names and which is still changing. Every figure is a sum of seconds: GPU hours are gpu_seconds / 3600, and GPU utilization is gpu_busy_seconds / gpu_seconds. An hour in which a node changed cluster is split between the two by the time it spent in each.

Only nodes that were up at some moment of the period count: a node a cluster lists but that never reported metrics or ran a task in the period is left out of the list and of every figure. A node's segments are the stretches it was up, so the time it was not up stays empty, and node time, peaks and the nodes at either end of the period count up time only.

cluster_id narrows the report to the time spent in one cluster: the nodes up in it at some moment of the period, each with its stretches there alone. gpu_model narrows it to the nodes with that model; its options, gpu_models, are the models found in the cluster filtered on, if any.

Authorizations:
ApiKeyAuth
query Parameters
cluster_id
string

Only the time spent in this cluster, as all_clusters lists them: the nodes up in it at some moment of the period, each with its stretches there alone. Every figure in the report then covers that time, and gpu_models lists the models found there.

end
string

Period end, RFC3339; defaults to now. The part of the period that has not happened yet is not read, so an end in the future reads up to now.

gpu_model
string

Only the nodes with this GPU model, as gpu_models in the response lists them. Every figure in the report then covers those nodes alone.

start
string

Period start, RFC3339; defaults to 30 days before end.

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/usage/fleet" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "all_clusters": [
    ],
  • "as_of": "example",
  • "clusters": [
    ],
  • "coverage": {
    },
  • "end": "2026-03-31T23:59:59Z",
  • "gpu_models": [
    ],
  • "nodes": [
    ],
  • "start": "2026-01-01T00:00:00Z"
}

Node usage

One node over a period: where it was, its GPU use there, what happened to it — cluster moves, another machine behind the same node — and the jobs it ran. Same period, sources and units as GET /v1/usage/fleet.

Authorizations:
ApiKeyAuth
path Parameters
nodeId
required
string

Node ID

query Parameters
end
string

Period end, RFC3339; defaults to now. The part of the period that has not happened yet is not read, so an end in the future reads up to now.

start
string

Period start, RFC3339; defaults to 30 days before end.

Responses

Request samples 

curl -X GET "https://tenant.api.neospace.ai/v1/usage/nodes/{nodeId}" \
  -H "x-api-key: $API_KEY"

Response samples

Content type
application/json
{
  • "all_clusters": [
    ],
  • "as_of": "example",
  • "clusters": [
    ],
  • "coverage": {
    },
  • "end": "2026-03-31T23:59:59Z",
  • "events": [
    ],
  • "jobs": [
    ],
  • "node": {
    },
  • "start": "2026-01-01T00:00:00Z"
}