Run envelopes include artifact metadata. Fetch each artifact body with GET /artifacts/{id}.
GET /artifacts/{id}
curl https://havilo.ai/api/v1/artifacts/550e8400-e29b-41d4-a716-446655440001 \
-H "Authorization: Bearer $HAVILO_API_KEY"Table Artifact
Table artifacts include columns and rows. Rows are objects keyed by column name whenever possible.
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"object": "artifact",
"kind": "table",
"title": "climate-tech Startups",
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": 1714500018000,
"row_count": 3,
"columns": ["Name", "Description", "Website", "Location"],
"rows": [
{
"Name": "Example Startup",
"Description": "A short company description.",
"Website": "https://example.com",
"Location": "San Francisco, CA"
}
]
}Text Artifact
Text artifacts contain long-form generated output.
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"object": "artifact",
"kind": "text",
"title": "Company Dossier",
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": 1714500018000,
"content": "## Company Dossier\n\n### Background\n\n..."
}Entity-Card Artifact
Entity-card artifacts contain structured entity summary content.
{
"id": "550e8400-e29b-41d4-a716-446655440004",
"object": "artifact",
"kind": "entity_card",
"title": "Entity Card",
"run_id": "550e8400-e29b-41d4-a716-446655440000",
"created_at": 1714500018000,
"content": {
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440002"
}
}
}Linked Entities
Use include=links to return normalized artifact-to-entity links:
curl "https://havilo.ai/api/v1/artifacts/550e8400-e29b-41d4-a716-446655440003?include=links" \
-H "Authorization: Bearer $HAVILO_API_KEY"The default response is unchanged when include=links is omitted.
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"object": "artifact",
"kind": "text",
"title": "Company Dossier",
"created_at": 1714500018000,
"entity_refs": [
{
"entity_id": "550e8400-e29b-41d4-a716-446655440002",
"role": "subject",
"is_primary": true,
"source": "EXTRACTOR",
"source_detail": "text_editor",
"content_path": "metadata.subject_entity_id"
}
]
}Links cover the artifacts whose entities are structural: email recipients, and the record a dossier and its entity card are about. Table artifacts return an empty entity_refs — a table's entity references are the linked values in rows, so read them there. Links are also derived only once an artifact is saved; entity_refs is empty for a run's transient output.
Artifact links are not entity-to-entity relationships. Multiple links can be primary at the same time, and automatic extractors do not mutate manual links.
Record links
Table cells and a run's message name records as markdown links:
[Acme Corp](entity=550e8400-e29b-41d4-a716-446655440002)| Kind | Points at |
|---|---|
entity | A record. Look it up with GET /entities/resolve. |
note | A note. |
artifact | An artifact. Fetch it with GET /artifacts/{id}. |
entity_type | A record type, such as Company. |
entity_list | A saved list. |
Show the label to people; the id is for your code. These are not web URLs, so a markdown renderer needs them turned into your own links or into plain text.
Artifact Metadata
Run envelopes include only artifact metadata:
{
"artifacts": [
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"kind": "table",
"title": "climate-tech Startups",
"row_count": 3
}
]
}Use the artifact endpoint for the full body.