Ingestion configuration is optional. If omitted, Jockey uses the default extraction. Configure ingestion when you know what to extract. It helps Jockey emphasize the right signals and produce more reliable extraction.

Choose the approach that fits your use case:

• Default (no configuration): No setup required. Use it for getting started or quick prototyping.
• Natural language description: Describe what to extract in plain language. Use it when you know the domain but not the exact fields.
• JSON Schema: Define the exact fields and types to extract. Use it when downstream code expects specific typed fields.

Natural language description

Use this approach for exploratory work when you don’t yet know the exact fields you need.

Example

The following example focuses extraction on brand mentions, product appearances, audience reactions, and visual tone. Copy and paste the code below, replacing the placeholders surrounded by <> with your values.

1
from twelvelabs import TwelveLabs, IngestionConfig, EnrichmentConfig_Description
2
3
client = TwelveLabs(api_key="<YOUR_API_KEY>")
4
5
store = client.knowledge_stores.create(
6
    name="<YOUR_KNOWLEDGE_STORE_NAME>",
7
    ingestion_config=IngestionConfig(
8
        enrichment_config=EnrichmentConfig_Description(
9
            description="Focus on brand mentions, product appearances, audience reactions, and visual tone"
10
        )
11
    ),
12
)
13
print(f"Knowledge store created: {store.id}")

Code explanation

JSON Schema

Use this approach when downstream code expects specific typed fields.

Example

The following example extracts metadata about people, locations, and activities from each video shot. Copy and paste the code below, replacing the placeholders surrounded by <> with your values.

1
from twelvelabs import (
2
    TwelveLabs,
3
    IngestionConfig,
4
    EnrichmentConfig_JsonSchema,
5
    EnrichmentConfigJsonSchemaJsonSchema,
6
)
7
8
client = TwelveLabs(api_key="<YOUR_API_KEY>")
9
10
store = client.knowledge_stores.create(
11
    name="<YOUR_KNOWLEDGE_STORE_NAME>",
12
    ingestion_config=IngestionConfig(
13
        enrichment_config=EnrichmentConfig_JsonSchema(
14
            json_schema=EnrichmentConfigJsonSchemaJsonSchema(
15
                type="object",
16
                properties={
17
                    "people_count": {"type": "integer", "description": "Number of people visible in the frame"},
18
                    "location": {"type": "string", "description": "Name or type of the location"},
19
                    "suspicious_activity": {"type": "boolean", "description": "Whether suspicious activity is detected"},
20
                    "scene_description": {"type": "string", "description": "Brief description of what is happening"},
21
                },
22
                required=["people_count", "scene_description"],
23
            )
24
        )
25
    ),
26
)
27
print(f"Knowledge store created: {store.id}")

Code explanation

JSON Schema keywords

The platform accepts the following JSON Schema keywords:

Notes:

• Include a description field in every property. The platform uses this text to guide extraction, and omitting it returns a 422 error.
• Use the required keyword to specify which fields must appear in every result.
• Set the additionalProperties keyword to true or false to control strict shapes.
• Do not use nullable fields. To make a field optional, omit it from the required array.
• Do not include unknown keywords. The platform rejects them with a 422 error.

Not supported

The platform does not support the following JSON Schema keywords:

• Schema composition: anyOf, allOf, oneOf, not
• Conditional schemas: if / then / else
• Property dependencies: dependentSchemas, dependentRequired
• Object size constraints: minProperties, maxProperties
• String constraints: pattern, minLength, maxLength
• Number constraints: exclusiveMinimum, exclusiveMaximum, multipleOf
• Value constraints: const
• Null handling: nullable, type arrays (e.g., ["string", "null"])
• Annotative keywords: default, examples, readOnly, writeOnly
• References and reuse: $ref, $defs, definitions

Common pitfalls

• Overly specific schemas can limit extraction. If the schema is too specific, Jockey may miss relevant content. Start broad, then narrow the schema as you learn what you need.
• General descriptions can lead to broad extraction. If the description is too general, Jockey may return results that are broader than you need. Name the fields, entities, or patterns you want Jockey to emphasize.
• Programmatically generated schemas may include unsupported keywords. If you use tools like pydantic.model_json_schema(), the output may contain annotative keywords such as default, examples, and readOnly. Strip these before submitting. The platform rejects unknown keywords with a 422 error.

Jupyter notebook