Skip to main content
Docs

Search guides and API endpoints, for example “Idempotency-Key” or “submit job”.

    API reference

    Your models

    Models you trained, of every type: list, inspect, rename, tag and delete.

    On this page

    List your MPNN models (deprecated)

    GET/api/v1/user-models/mpnn

    API key or tokenDeprecated

    Deprecated. Use GET /user-models?model_type=mpnn and GET /user-models/{model_id}. This route stops working after Fri, 15 Jan 2027 00:00:00 GMT.

    Parameters

    Query parameters
    NameTypeDescription
    model_namestring

    Example request

    curl "https://api.cognichem.com/api/v1/user-models/mpnn" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

    Responses

    Successful Response · application/json · GetMPNNModelsResponse

    Response fields
    FieldTypeDescription
    model_infoobject | null

    A dictionary containing MPNN model information.

    model_names[]string[] | null

    A list of MPNN model names.

    models[]SavedModelRef[] | null

    The same models with their ids, for scoring jobs.

    models.classes_by_target[]((string | integer)[])[] | null

    Class labels per target of a multiclass model (models trained since #976); a scoring job names one as score_class.

    models.created_atstring | null

    When training started (your models only).

    models.model_idrequiredstring

    user_models.id (mdl-<ULID>); pass it as model_id to model-score or Thompson Sampling's StoredModelEvaluator.

    models.model_typerequiredstring

    Model family (mpnn); pass it as model_type to inference.

    models.namerequiredstring

    Display name; pass it as model_name to inference.

    models.statusrequiredstring

    training, ready or failed; only ready models predict.

    One of: "training", "ready", "failed"

    models.target_names[]string[] | null

    The model's targets, primary first; a scoring job may name another as score_target.

    models.taskstring | null

    regression, binary or multiclass, when recorded.

    models.unitstring | null

    Unit of the predicted value, when the model declares one.

    models.visibilityrequiredstring

    private (yours) or public.

    One of: "private", "public"

    Delete one of your MPNN models (deprecated)

    DELETE/api/v1/user-models/mpnn

    API key or tokenDeprecated

    Deprecated. Use DELETE /user-models/{model_id}. This route stops working after Fri, 15 Jan 2027 00:00:00 GMT.

    Parameters

    Query parameters
    NameTypeDescription
    model_namerequiredstring

    Example request

    curl -X DELETE "https://api.cognichem.com/api/v1/user-models/mpnn?model_name=MODEL_NAME" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

    Responses

    Successful Response · application/json · MessageResponse

    Response fields
    FieldTypeDescription
    messagerequiredstring

    The message content.

    List your saved models

    GET/api/v1/user-models

    API key or token

    List the models you trained, oldest first, with your model quota.

    Each entry has the model_id that scoring jobs take and the model_type and name that inference takes, plus its description, tags and validation / test metrics (fold_metrics). quota counts your models against your plan's cap; failed models never count.

    Parameters

    Query parameters
    NameTypeDescription
    model_typestring

    Only models of this type (for example mpnn).

    Limits: pattern ^[a-z][a-z0-9_]*$

    include_failedboolean

    Also list your newest failed models (up to 100), whose training stopped without a model.

    Default: false

    Example request

    curl "https://api.cognichem.com/api/v1/user-models?model_type=mpnn" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

    Responses

    Successful Response · application/json · UserModelsResponse

    Response fields
    FieldTypeDescription
    models[]requiredUserModelSummary[]

    Your models, oldest first.

    models.classes_by_target[]((string | integer)[])[] | null
    models.created_atstring | null
    models.descriptionstring | null

    Your description.

    models.failure_reasonstring | null

    Why a failed model has no bundle (error, cancelled or no_bundle).

    models.fold_metricsmap<string, number>

    Validation, cross-validation and test metrics such as test/r2 or cv/roc_auc.

    models.model_idrequiredstring
    models.model_typerequiredstring
    models.namerequiredstring
    models.ready_atstring | null

    When training finished.

    models.statusrequiredstring

    One of: "training", "ready", "failed"

    models.tags[]string[]

    Your tags.

    models.target_names[]string[] | null
    models.taskstring | null
    models.unitstring | null
    models.visibilityrequiredstring

    One of: "private", "public"

    quotaModelQuota | null

    Your model count and cap; null if it could not be read.

    quota.limitrequiredinteger

    Your tier's cap; training a new model past it fails before it starts.

    quota.tierrequiredinteger

    Your subscription tier.

    quota.usedrequiredinteger

    Models that count against the cap (training or ready; failed models never count).

    Get one of your saved models

    GET/api/v1/user-models/{model_id}

    API key or token

    Get one of your models with its training settings, metrics and history.

    Parameters

    Path parameters
    NameTypeDescription
    model_idrequiredstring

    Limits: pattern ^mdl-[0-9A-HJKMNP-TV-Z]{26}$

    Example request

    curl "https://api.cognichem.com/api/v1/user-models/mdl-01JABCDEFGHJKMNPQRSTVWXYZ0" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

    Responses

    Successful Response · application/json · SavedModelDetail

    Response fields
    FieldTypeDescription
    classes_by_target[]((string | integer)[])[] | null
    configobject

    Training settings (unit and the family's parameters).

    created_atstring | null
    descriptionstring | null
    edited_atstring | null

    Your last edit of name, description or tags.

    failed_atstring | null

    When training failed.

    failure_messagestring | null

    The training job's message when the model failed.

    failure_reasonstring | null
    fold_metricsmap<string, number>
    framework_versionsobject

    Library versions the model was trained with.

    history[]object[]

    Per-epoch training curve (downsampled); empty for families without one.

    job_idstring | null

    The training job's process_id; null once that job is deleted.

    metrics_summaryobject

    Validation and test metrics; keys depend on the model family.

    model_idrequiredstring
    model_typerequiredstring
    namerequiredstring
    ready_atstring | null
    size_bytesinteger

    Stored bundle size (0 until ready).

    Default: 0

    staterequiredstring

    running, finished or failed (status as the My Models page shows it).

    statusrequiredstring

    One of: "training", "ready", "failed"

    tags[]string[]
    target_names[]string[] | null
    taskstring | null
    training_jobTrainingJobSummary | null

    The training job, while it exists.

    training_job.finished_atstring | null
    training_job.job_namestring | null

    Your job name.

    training_job.process_idrequiredstring

    Job id for GET /jobs/status and the Job Queue.

    training_job.runtime_secondsnumber | null

    Billed runtime.

    training_job.started_atstring | null
    training_job.statusstring | null

    Job status.

    training_job.status_messagestring | null

    The job's last message (the error when it failed).

    unitstring | null
    visibilityrequiredstring

    One of: "private", "public"

    Rename, describe or tag one of your saved models

    PATCH/api/v1/user-models/{model_id}

    API key or token

    Change a model's name, description or tags; fields you leave out keep their values.

    Inference selects your models by model_type and name, so after a rename pass the new name as model_name. Jobs and workflows that take model_id are unaffected.

    Parameters

    Path parameters
    NameTypeDescription
    model_idrequiredstring

    Limits: pattern ^mdl-[0-9A-HJKMNP-TV-Z]{26}$

    Request body

    application/json · UpdateSavedModelRequest

    Request fields
    FieldTypeDescription
    descriptionstring | null

    New description; "" or null clears it.

    Limits: max length 2000

    namestring | null

    New name, unique among your models of this model_type. Inference selects models by name, so callers passing the old model_name must switch; model_id callers are unaffected.

    Limits: max length 128

    tags[]string[] | null

    Replacement tags (duplicates ignoring case are dropped); [] clears them.

    Limits: max items 20

    Example request

    curl -X PATCH "https://api.cognichem.com/api/v1/user-models/mdl-01JABCDEFGHJKMNPQRSTVWXYZ0" \
  -H "X-Api-Key: $COGNICHEM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "aqsoldb-logs-v2"
}'

    Responses

    Successful Response · application/json · SavedModelDetail

    Response fields
    FieldTypeDescription
    classes_by_target[]((string | integer)[])[] | null
    configobject

    Training settings (unit and the family's parameters).

    created_atstring | null
    descriptionstring | null
    edited_atstring | null

    Your last edit of name, description or tags.

    failed_atstring | null

    When training failed.

    failure_messagestring | null

    The training job's message when the model failed.

    failure_reasonstring | null
    fold_metricsmap<string, number>
    framework_versionsobject

    Library versions the model was trained with.

    history[]object[]

    Per-epoch training curve (downsampled); empty for families without one.

    job_idstring | null

    The training job's process_id; null once that job is deleted.

    metrics_summaryobject

    Validation and test metrics; keys depend on the model family.

    model_idrequiredstring
    model_typerequiredstring
    namerequiredstring
    ready_atstring | null
    size_bytesinteger

    Stored bundle size (0 until ready).

    Default: 0

    staterequiredstring

    running, finished or failed (status as the My Models page shows it).

    statusrequiredstring

    One of: "training", "ready", "failed"

    tags[]string[]
    target_names[]string[] | null
    taskstring | null
    training_jobTrainingJobSummary | null

    The training job, while it exists.

    training_job.finished_atstring | null
    training_job.job_namestring | null

    Your job name.

    training_job.process_idrequiredstring

    Job id for GET /jobs/status and the Job Queue.

    training_job.runtime_secondsnumber | null

    Billed runtime.

    training_job.started_atstring | null
    training_job.statusstring | null

    Job status.

    training_job.status_messagestring | null

    The job's last message (the error when it failed).

    unitstring | null
    visibilityrequiredstring

    One of: "private", "public"

    Delete one of your saved models

    DELETE/api/v1/user-models/{model_id}

    API key or token

    Delete one of your models. Its name and its slot in your model quota are free again at once.

    Parameters

    Path parameters
    NameTypeDescription
    model_idrequiredstring

    Limits: pattern ^mdl-[0-9A-HJKMNP-TV-Z]{26}$

    Example request

    curl -X DELETE "https://api.cognichem.com/api/v1/user-models/mdl-01JABCDEFGHJKMNPQRSTVWXYZ0" \
  -H "X-Api-Key: $COGNICHEM_API_KEY"

    Responses

    Successful Response · application/json · MessageResponse

    Response fields
    FieldTypeDescription
    messagerequiredstring

    The message content.